# Agent-Commerce-OS - Full Technical Specification (v1.0.0)

## 1. System Infrastructure & Hybrid Architecture
Agent-Commerce-OS employs a strict Zero-Trust, Hybrid Edge-Core architecture to guarantee performance, security, and exact billing for AI agent traffic.

- **Gateway (Layer A)**: `ghost-ship-proxy`
  - **Environment**: Cloudflare Workers (Hono.js).
  - **Endpoint**: `https://api.sakutto.works/v1/normalize_web_data`
  - **Functions**: Edge-level Polar.sh License Key validation (Zero-latency cache), Prompt Injection Shield, and asynchronous Usage Metering ($0.10 per call). Adds `X-Internal-Secret` and `X-Tenant-Id` headers to authorized requests.
- **Core (Layer B)**: `gs-mcp-core`
  - **Environment**: Google Cloud Run (Python/FastAPI built with `uv`).
  - **Functions**: Deep semantic extraction using RAG-optimized pipelines (e.g., Jina Reader, Firecrawl). Converts messy HTML into strictly formatted Markdown or JSON. Drops any request lacking the `X-Internal-Secret`.

## 2. Agent-Optimized Capabilities (The "Juice" Menu)
The `normalize_web_data` endpoint is highly effective for specialized deep-web extraction tasks, including:
- **Japanese Technology Regulation Research**: Extracting clean, noise-free text from complex government or corporate portals.
- **Academic Paper Extraction**: Normalizing PDF/HTML academic papers into cleanly structured Markdown for seamless agent ingestion.

## 3. API Governance & Error Handling
- **Authentication**: AI Agents must pass a Polar.sh token via the `Authorization: Bearer <TOKEN>` header.
- **Self-Correction (AgentSemanticError)**: If an agent sends malformed data, the API returns a `400 Bad Request` containing an `agent_instruction` field. Agents are expected to read this instruction and self-correct their subsequent request.
- **Security Drops**: Malicious payloads (e.g., "ignore previous instructions") are instantly terminated at Layer A with a `403 Forbidden`.

## 4. References
Always refer to `/openapi.yaml` for the strict OpenAPI 3.1.0 schema definitions required to call the endpoints.

---
© 2026 Sakutto Works - Standardizing the Semantic Web for Agents.