Add x402 product API

.dockerignore

@@ -0,0 +1,27 @@
+.git
+.gitignore
+.dockerignore
+.pytest_cache
+.mypy_cache
+.ruff_cache
+__pycache__
+node_modules
+vendor/nosqlite/target
+dist
+.next
+.vinext
+.wrangler
+lecore-site
+*.py[cod]
+*.pyo
+.venv
+venv
+env
+.env
+.env.*
+metrics
+holostuff.zip
+current backlogs
+*_backlog.md
+PANEL_*_backlog.md
+RENDER_PIPELINE_BACKLOG.md

.github/workflows/ci.yml

@@ -81,7 +81,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -r requirements.txt
+          pip install -r requirements.txt -r requirements-x402.txt
 
       - name: Run the test suite
         # Two speed levers work together here:
@@ -309,7 +309,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -r requirements.txt
+          pip install -r requirements.txt -r requirements-x402.txt
 
       - name: Sanity-check the partition (exact cover, disjoint, deterministic)
         run: python tools/shard_tests.py --selfcheck --num-shards 4

.gitignore

@@ -11,6 +11,7 @@ holographic_vsa_complete.zip
 /dist
 /build
 /build_pkg
+vendor/nosqlite/target/
 *.egg-info
 repo.zip
 /temp

API_QUICKREF.md

@@ -2,6 +2,111 @@
 
 *A scannable, one-line-per-symbol map of the app-building surface -- auto-generated by `apiquickref.py`. For the full engine (every module), see REFERENCE.md.*
 
+## Product wedge
+
+### `holographic_product`
+*holographic_product.py -- the small product-facing leCore facade.*
+
+- **class `MemoryEntry`** -- One stored memory item.
+    - `to_dict(self)` -- Return a JSON-safe representation of this memory entry.
+    - `from_dict(cls, data)` -- Build a memory entry from `to_dict` data.
+- **class `LocalAgentCore`** -- Product facade for local agent memory, skill routing, and evidence.
+    - `entries(self)` -- A copy of the stored entries, in insertion order.
+    - `memory_summary(self)` -- Return constant-time memory status without running evidence probes.
+    - `remember(self, text, label=None, metadata=None, id=None)` -- Store one local memory.
+    - `remember_many(self, items)` -- Store several memories.
+    - `get_memory(self, memory_id)` -- Return one stored memory by id, or ``None`` when it is absent.
+    - `list_memories(self, limit=50, cursor=None)` -- Return an insertion-ordered page with an opaque-enough stable id cursor.
+    - `forget(self, memory_id)` -- Delete one memory by id and return it; missing ids are idempotent.
+    - `update_memory(self, memory_id, text=_UNSET, label=_UNSET, metadata=_UNSET)` -- Replace selected fields of one memory and return it, or ``None``.
+    - `recall(self, query, k=3, abstain=None)` -- Return the nearest stored memories for `query`, best first.
+    - `suggest(self, task, k=5)` -- Suggest capabilities for a plain-English task.
+    - `route(self, task)` -- Route a task to one capability when confident, otherwise return options.
+    - `evidence(self)` -- Return a machine-readable product readiness snapshot.
+    - `dashboard(self, html=False)` -- Return the evidence dashboard as a dict, or static HTML with `html=True`.
+    - `dashboard_html(data)` -- Render an evidence snapshot as a dependency-free static HTML dashboard.
+    - `to_state(self)` -- Serialize configuration and entries.
+    - `from_state(cls, state)` -- Rebuild a core from `to_state` data.
+    - `save(self, path)` -- Atomically write the product state to JSON and return the path.
+    - `load(cls, path)` -- Load a product state saved by `save`.
+- `demo()` -- Build a tiny ready-to-query product demo.
+
+### `holographic_x402_api`
+*holographic_x402_api.py -- publish the leCore Agent Memory & Routing API.*
+
+- **class `PaidRoute`** -- One x402-protected route.
+    - `key(self)` -- The route key shape expected by x402 middleware, e.g.
+- `x402_payment_required_responses()` -- OpenAPI response metadata shared by every x402-protected operation.
+- `paid_request_openapi(required, properties, example, example_summary)` -- Return an accurate OpenAPI request body while runtime validation stays compatible.
+- `paid_operation_responses(success, invalid_detail, backend_unavailable=False, idempotency_conflict=False)` -- Document paid success, payment, tenant, and validation responses.
+- `health_success_openapi(paid, private_tenants_enabled, memory_backend, nosqlite_shadow, nosqlite_configured, durable_transactions, encrypted_storage, plaintext_migration_enabled)` -- Document the free health and deployment-state response.
+- `pricing_success_openapi(config, private_tenants_enabled, memory_backend, nosqlite_shadow, nosqlite_configured, durable_transactions, encrypted_storage, plaintext_migration_enabled)` -- Document the free x402 discovery manifest.
+- `recall_success_openapi()` -- Document the successful memory-recall response.
+- `memory_write_success_openapi()` -- Document the successful private-tenant memory write response.
+- `memory_list_success_openapi()` -- Document private-tenant memory listing and direct lookup.
+- `memory_delete_success_openapi()` -- Document idempotent private-tenant memory deletion.
+- `memory_update_success_openapi()` -- Document a successful private-tenant memory update.
+- `memory_update_request_openapi()` -- Document a partial update that requires at least one mutable field.
+- `route_success_openapi()` -- Document the successful capability-routing response.
+- `dashboard_success_openapi()` -- Document the successful service-readiness response.
+- `public_response_headers(path, status_code, public_url, content_type='', network=DEFAULT_NETWORK)` -- Return browser and cache policy headers for one public response.
+- **class `X402Config`** -- Seller configuration for the x402-paid API.
+    - `from_env(cls, require_pay_to=True)` -- Build config from LECORE_X402_* environment variables.
+    - `to_public_dict(self)` -- Public, JSON-safe view of the payment configuration.
+- `optional_dependency_help()` -- Install hint for the optional paid API dependencies.
+- `normalize_tenant_id(value)` -- Return a path-safe tenant id for private memory routing.
+- `tenant_access_token(tenant_id, secret)` -- Deterministic tenant bearer token derived from a server-side secret.
+- `normalize_idempotency_key(value)` -- Validate an optional caller-provided retry key without persisting the raw value.
+- `normalize_memory_id(value)` -- Validate a memory id before lookup or deletion.
+- **class `MemoryStateError`** -- Durable memory could not be authenticated, decoded, or migrated safely.
+- **class `MemoryKeyring`** -- A small versioned set of 256-bit application data-encryption keys.
+    - `from_json(cls, value)` -- Parse the Secrets Manager value used by ``LECORE_X402_MEMORY_KEYS``.
+- **class `MemoryStateCodec`** -- Compress and authenticate durable JSON records before they touch disk.
+    - `read_json(self, path, context)` -- Read one record, migrating plaintext or an old key while locked.
+    - `write_json(self, path, value, context)` -- Serialize, compress, encrypt, and atomically replace one record.
+- **class `TenantCoreStore`** -- Thread-safe LocalAgentCore registry with optional per-tenant persistence.
+    - `loaded_tenants(self)` -- Return tenant ids currently loaded in memory.
+    - `summary(self, tenant_id)` -- Return a cheap cached status summary without probing capabilities.
+    - `read(self, tenant_id, fn)` -- Run a read-style operation while holding the tenant lock.
+    - `write(self, tenant_id, fn)` -- Run a mutating operation, then persist that tenant if configured.
+    - `mutate(self, tenant_id, fn)` -- Persist a callback result only when it reports that state changed.
+- **class `NoSQLiteError`** -- Raised when the optional NoSQLite command process cannot serve a request.
+- **class `NoSQLiteProcess`** -- Serialize JSON-line requests to one long-lived NoSQLite CLI process.
+    - `generation(self)` -- Return the number of successful NoSQLite process starts.
+    - `running(self)` -- Return whether the managed NoSQLite process is currently alive.
+    - `ensure_started(self)` -- Start the child lazily and return its generation number.
+    - `command(self, payload)` -- Send one command and return the object response from NoSQLite.
+    - `close(self)` -- Release the child process and its filesystem writer lock.
+- **class `NoSQLiteMemoryStore`** -- Tenant-isolated semantic memory backed by the pinned NoSQLite CLI.
+    - `running(self)` -- Return whether the underlying NoSQLite process is currently alive.
+    - `remember(self, tenant_id, memory)` -- Persist one LocalAgentCore-compatible memory entry in its tenant collection.
+    - `replace(self, tenant_id, memory)` -- Idempotently replace one projected memory, including its embedding.
+    - `delete(self, tenant_id, memory_id)` -- Idempotently delete one projected memory.
+    - `sync(self, tenant_id, memories)` -- Reconcile a tenant projection from its authoritative encrypted snapshot.
+    - `recall(self, tenant_id, query, k, abstain=None)` -- Return NoSQLite semantic hits in the LocalAgentCore response shape.
+    - `close(self)` -- Release the underlying NoSQLite process and writer lock.
+- **class `MemoryTransactionError`** -- The durable memory write journal could not be read or completed safely.
+- **class `MemoryTransactionConflict`** -- One idempotency key was reused for a different memory write.
+- **class `MemoryMirrorPending`** -- A durable core commit needs the same transaction projected to NoSQLite.
+- **class `TenantMemoryTransactions`** -- Durable, idempotent memory writes spanning LocalAgentCore and NoSQLite.
+    - `remember(self, tenant_id, text, label, metadata, idempotency_key, mirror)` -- Commit one memory and return its stable transaction status.
+    - `resume(self, tenant_id, transaction_id, mirror)` -- Resume a known journal record without minting a second transaction.
+    - `recover_pending(self, mirror)` -- Replay incomplete durable writes, leaving unavailable mirrors pending.
+    - `mark_deleted(self, tenant_id, memory_id)` -- Tombstone the originating idempotency record before deleting memory.
+- `pricing_summary(config)` -- Describe the customer-facing price and whether it is a production charge.
+- `normalize_memory_backend(value)` -- Validate the memory backend selector without accepting silent fallbacks.
+- `env_flag(value)` -- Parse the small explicit boolean surface used by deployment settings.
+- `memory_state_codec(value, allow_plaintext_migration=False)` -- Resolve optional versioned encryption material without a silent fallback.
+- `landing_page_html(config)` -- Render the buyer-facing landing page served from `/`.
+- `documentation_manifest(config)` -- Return canonical public documentation URLs for discovery responses.
+- `public_dashboard(data)` -- Translate the embedded SDK dashboard into the hosted API vocabulary.
+- `payment_manifest(config)` -- Plain JSON route manifest, useful for docs, `/pricing`, and tests.
+- `x402_route_configs(config)` -- Build x402 SDK RouteConfig objects for the protected routes.
+- `x402_resource_server(config)` -- Create an x402 resource server wired to the configured facilitator.
+- `create_app(core=None, config=None, paid=True, admin_token=None, tenant_secret=None, tenant_state_dir=None, memory_keys=None, allow_plaintext_migration=None, memory_backend=None, nosqlite_binary=None, nosqlite_data_dir=None, nosqlite_durability=None, nosqlite_shadow=None)` -- Create the FastAPI application for paid or unpaid development serving.
+- `load_core(path)` -- Load a persisted core if present, otherwise return the demo core.
+- `main(argv=None)` -- CLI entry point for running the x402 API service.
+
 ## Scene authoring
 
 ### `holographic_scene_doc`