patchr 0.1.0__py3-none-any.whl

picux/contracts/routes.py

@@ -0,0 +1,980 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ContractEndpoint:
+    method: str
+    path: str
+    opId: str
+    tag: str
+    desc: str
+    mcpTool: str = ""
+
+    def toMap(self) -> dict[str, Any]:
+        return {
+            "method": self.method,
+            "path": self.path,
+            "opId": self.opId,
+            "tag": self.tag,
+            "desc": self.desc,
+            "mcpTool": self.mcpTool,
+        }
+
+
+CONTRACT_ENDPOINTS: tuple[ContractEndpoint, ...] = (
+    ContractEndpoint("GET", "/healthz", "healthz", "runtime", "Return Picux runtime health."),
+    ContractEndpoint("GET", "/runtime", "runtimeSummary", "runtime", "Return runtime configuration summary."),
+    ContractEndpoint("GET", "/v1/status", "apiStatus", "runtime", "Return public Picux API status.", "picux.apiStatus"),
+    ContractEndpoint("GET", "/openapi.json", "openapiSpec", "contract", "Return the OpenAPI contract."),
+    ContractEndpoint("GET", "/v1/contract", "contractSummary", "contract", "Return a compact Picux contract summary."),
+    ContractEndpoint("GET", "/v1/manifest", "integrationManifest", "contract", "Return the Picux integration manifest.", "picux.manifest"),
+    ContractEndpoint("GET", "/v1/protocol-map", "protocolMap", "contract", "Return the agent-readable Picux protocol map.", "picux.protocolMap"),
+    ContractEndpoint("POST", "/v1/handshake", "integrationHandshake", "contract", "Validate an external Picux integration handshake.", "picux.handshake"),
+    ContractEndpoint("GET", "/v1/schemas", "schemaCatalog", "contract", "List Picux JSON Schema contracts.", "picux.listSchemas"),
+    ContractEndpoint(
+        "GET",
+        "/v1/schemas/{schemaId}",
+        "getSchema",
+        "contract",
+        "Fetch a Picux JSON Schema contract.",
+        "picux.getSchema",
+    ),
+    ContractEndpoint("POST", "/mcp", "mcpRpc", "mcp", "Handle MCP JSON-RPC tool calls."),
+    ContractEndpoint("GET", "/v1/a2a/contract", "a2aContract", "a2a", "Return the A2A envelope contract.", "picux.a2aContract"),
+    ContractEndpoint(
+        "POST",
+        "/v1/security/policy/evaluate",
+        "evaluatePolicy",
+        "security",
+        "Evaluate mandate-session and capability-grant policy.",
+        "picux.evaluatePolicy",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/security/secrets/check",
+        "checkSecrets",
+        "security",
+        "Validate scoped secret references without exposing secret values.",
+        "picux.checkSecrets",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/tools/nlp",
+        "nlpTool",
+        "tools",
+        "Classify a raw user query, detect follow-up context, and select Picux domain routing.",
+        "picux.nlpTool",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/tools/imageReader",
+        "imageReader",
+        "tools",
+        "Read image attachments and return query-relevant evidence signals.",
+        "picux.imageReader",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/tools/browserReader",
+        "browserReader",
+        "tools",
+        "Prepare or execute headless browser source reads for HUNT and RESOLVE.",
+        "picux.browserReader",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/tools/map",
+        "mapTool",
+        "tools",
+        "Search source-bound local places for HUNT and RESOLVE using Google Places/Maps or an adapter-neutral fallback.",
+        "picux.mapTool",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/tools/portalBrowser",
+        "portalBrowser",
+        "tools",
+        "Run a fail-closed authenticated portal action and return proof-ready artifacts.",
+        "picux.portalBrowser",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/sandbox/midnight-arbitrage",
+        "runSandbox",
+        "sandbox",
+        "Run the deterministic Midnight Arbitrage sandbox.",
+        "picux.runSandbox",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/orchestrator/run",
+        "runOrchestrator",
+        "orchestrator",
+        "Run Picux orchestration across HUNT, RESOLVE, BRIDGE, PROXY, and PAY from a user request.",
+        "picux.runOrchestrator",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/benchmarks/local",
+        "runBenchmark",
+        "benchmarks",
+        "Run local protocol benchmark evidence.",
+        "picux.runBenchmark",
+    ),
+    ContractEndpoint("POST", "/v1/a2a/envelopes", "createA2AEnvelope", "a2a", "Create an A2A delegation envelope.", "picux.createA2AEnvelope"),
+    ContractEndpoint("GET", "/v1/a2a/envelopes", "listA2AEnvelopes", "a2a", "List durable A2A envelopes.", "picux.listA2AEnvelopes"),
+    ContractEndpoint(
+        "GET",
+        "/v1/a2a/envelopes/{msgId}",
+        "getA2AEnvelope",
+        "a2a",
+        "Fetch a durable A2A envelope.",
+        "picux.getA2AEnvelope",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/a2a/envelopes/{msgId}/update",
+        "updateA2AEnvelope",
+        "a2a",
+        "Update durable A2A envelope delivery status.",
+        "picux.updateA2AEnvelope",
+    ),
+    ContractEndpoint("POST", "/v1/events", "recordEvent", "events", "Record an integration event.", "picux.recordEvent"),
+    ContractEndpoint("GET", "/v1/events", "listEvents", "events", "List integration event outbox records.", "picux.listEvents"),
+    ContractEndpoint("GET", "/v1/events/{eventId}", "getEvent", "events", "Fetch an integration event.", "picux.getEvent"),
+    ContractEndpoint("POST", "/v1/events/{eventId}/ack", "ackEvent", "events", "Acknowledge an integration event.", "picux.ackEvent"),
+    ContractEndpoint(
+        "POST",
+        "/v1/event-subscriptions",
+        "createEventSubscription",
+        "events",
+        "Register an external event subscription.",
+        "picux.createEventSubscription",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/event-subscriptions",
+        "listEventSubscriptions",
+        "events",
+        "List external event subscriptions.",
+        "picux.listEventSubscriptions",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/event-subscriptions/{subId}",
+        "getEventSubscription",
+        "events",
+        "Fetch an external event subscription.",
+        "picux.getEventSubscription",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/event-subscriptions/{subId}/update",
+        "updateEventSubscription",
+        "events",
+        "Update an external event subscription.",
+        "picux.updateEventSubscription",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/event-deliveries",
+        "createEventDelivery",
+        "events",
+        "Create an external event delivery attempt.",
+        "picux.createEventDelivery",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/event-deliveries",
+        "listEventDeliveries",
+        "events",
+        "List external event delivery attempts.",
+        "picux.listEventDeliveries",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/event-deliveries/stats",
+        "eventDeliveryStats",
+        "events",
+        "Summarize external event delivery queue health.",
+        "picux.eventDeliveryStats",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/event-deliveries/ready",
+        "eventDeliveryReady",
+        "events",
+        "List claimable event delivery attempts without claiming them.",
+        "picux.eventDeliveryReady",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/event-deliveries/{deliveryId}",
+        "getEventDelivery",
+        "events",
+        "Fetch an external event delivery attempt.",
+        "picux.getEventDelivery",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/event-deliveries/{deliveryId}/chain",
+        "eventDeliveryChain",
+        "events",
+        "Fetch retry lineage for an event delivery attempt.",
+        "picux.eventDeliveryChain",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/event-deliveries/claim",
+        "claimEventDelivery",
+        "events",
+        "Claim the next queued event delivery attempt.",
+        "picux.claimEventDelivery",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/event-deliveries/claimBatch",
+        "claimEventDeliveries",
+        "events",
+        "Claim a batch of ready event delivery attempts.",
+        "picux.claimEventDeliveries",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/event-deliveries/sweep",
+        "sweepEventDeliveryLeases",
+        "events",
+        "Sweep expired event delivery leases back to queued.",
+        "picux.sweepEventDeliveryLeases",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/event-deliveries/{deliveryId}/retry",
+        "retryEventDelivery",
+        "events",
+        "Retry a failed or canceled event delivery attempt.",
+        "picux.retryEventDelivery",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/event-deliveries/{deliveryId}/fail",
+        "failEventDelivery",
+        "events",
+        "Fail an event delivery attempt and optionally schedule its retry.",
+        "picux.failEventDelivery",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/event-deliveries/{deliveryId}/complete",
+        "completeEventDelivery",
+        "events",
+        "Complete a claimed event delivery attempt.",
+        "picux.completeEventDelivery",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/event-deliveries/{deliveryId}/cancel",
+        "cancelEventDelivery",
+        "events",
+        "Cancel an event delivery attempt.",
+        "picux.cancelEventDelivery",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/event-deliveries/{deliveryId}/lease",
+        "renewEventDeliveryLease",
+        "events",
+        "Renew a claimed event delivery lease.",
+        "picux.renewEventDeliveryLease",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/event-deliveries/{deliveryId}/release",
+        "releaseEventDelivery",
+        "events",
+        "Release a claimed event delivery attempt back to queued.",
+        "picux.releaseEventDelivery",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/event-deliveries/{deliveryId}/update",
+        "updateEventDelivery",
+        "events",
+        "Update an external event delivery attempt.",
+        "picux.updateEventDelivery",
+    ),
+    ContractEndpoint("GET", "/v1/agents", "listAgents", "agents", "List registered external agents.", "picux.listAgents"),
+    ContractEndpoint("GET", "/v1/agents/{agentId}", "getAgent", "agents", "Fetch a registered external agent.", "picux.getAgent"),
+    ContractEndpoint("POST", "/v1/agents", "registerAgent", "agents", "Register an external agent card.", "picux.registerAgent"),
+    ContractEndpoint("POST", "/v1/agents/match", "matchAgents", "agents", "Match agents by domain and capabilities.", "picux.matchAgents"),
+    ContractEndpoint("POST", "/v1/agents/delegate", "delegateAgent", "agents", "Create an A2A delegation plan.", "picux.delegateAgent"),
+    ContractEndpoint(
+        "GET",
+        "/v1/bridge/connectors",
+        "listConnectors",
+        "bridge",
+        "List registered BRIDGE connectors.",
+        "picux.listConnectors",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/bridge/connectors/ready",
+        "listReadyConnectors",
+        "bridge",
+        "List Picux ready-made BRIDGE connector templates.",
+        "picux.listReadyConnectors",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/bridge/connectors/{connectorId}",
+        "getConnector",
+        "bridge",
+        "Fetch a registered BRIDGE connector.",
+        "picux.getConnector",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/bridge/connectors",
+        "registerConnector",
+        "bridge",
+        "Register a BRIDGE connector with scoped credential references.",
+        "picux.registerConnector",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/bridge/connectors/ready/install",
+        "installReadyConnectors",
+        "bridge",
+        "Install Picux ready-made BRIDGE connector templates into the active connector registry.",
+        "picux.installReadyConnectors",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/bridge/connection-sessions",
+        "createBridgeConnectionSession",
+        "bridge",
+        "Create a scoped BRIDGE connection session for client-owned adapter credentials and callbacks.",
+        "picux.createBridgeConnectionSession",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/bridge/connection-sessions",
+        "listBridgeConnectionSessions",
+        "bridge",
+        "List scoped BRIDGE connection sessions.",
+        "picux.listBridgeConnectionSessions",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/bridge/connection-sessions/{sessionId}",
+        "getBridgeConnectionSession",
+        "bridge",
+        "Fetch a scoped BRIDGE connection session.",
+        "picux.getBridgeConnectionSession",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/bridge/connection-sessions/{sessionId}/revoke",
+        "revokeBridgeConnectionSession",
+        "bridge",
+        "Revoke a scoped BRIDGE connection session.",
+        "picux.revokeBridgeConnectionSession",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/bridge/actions",
+        "createBridgeAction",
+        "bridge",
+        "Queue an adapter-neutral BRIDGE provider action and attach it to channel state.",
+        "picux.createBridgeAction",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/bridge/actions",
+        "listBridgeActions",
+        "bridge",
+        "List adapter-neutral BRIDGE provider actions.",
+        "picux.listBridgeActions",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/bridge/actions/{actionId}",
+        "getBridgeAction",
+        "bridge",
+        "Fetch an adapter-neutral BRIDGE provider action.",
+        "picux.getBridgeAction",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/bridge/actions/{actionId}/update",
+        "updateBridgeAction",
+        "bridge",
+        "Update BRIDGE provider action status, response, proof, or error state.",
+        "picux.updateBridgeAction",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/bridge/actions/{actionId}/run",
+        "runBridgeAction",
+        "bridge",
+        "Run a BRIDGE provider action through a Picux-hosted adapter or dispatch it to a client-hosted adapter.",
+        "picux.runBridgeAction",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/channels/threads",
+        "createChannelThread",
+        "channels",
+        "Create or upsert a durable cross-channel conversation thread.",
+        "picux.createChannelThread",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/channels/threads",
+        "listChannelThreads",
+        "channels",
+        "List durable cross-channel conversation threads.",
+        "picux.listChannelThreads",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/channels/threads/{threadId}",
+        "getChannelThread",
+        "channels",
+        "Fetch a durable cross-channel conversation thread.",
+        "picux.getChannelThread",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/channels/threads/{threadId}/timeline",
+        "channelThreadTimeline",
+        "channels",
+        "Fetch a unified channel thread timeline across touchpoints, provider actions, and callbacks.",
+        "picux.channelThreadTimeline",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/channels/touchpoints",
+        "recordTouchpoint",
+        "channels",
+        "Record an inbound, outbound, or internal touchpoint on a channel thread.",
+        "picux.recordTouchpoint",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/channels/touchpoints",
+        "listTouchpoints",
+        "channels",
+        "List channel touchpoints by thread, case, conversation, provider, or status.",
+        "picux.listTouchpoints",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/channels/touchpoints/{touchpointId}",
+        "getTouchpoint",
+        "channels",
+        "Fetch a channel touchpoint.",
+        "picux.getTouchpoint",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/channels/callbacks",
+        "ingestProviderCallback",
+        "channels",
+        "Ingest a provider callback and reconcile it into channel state.",
+        "picux.ingestProviderCallback",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/channels/callbacks",
+        "listProviderCallbacks",
+        "channels",
+        "List normalized provider callbacks.",
+        "picux.listProviderCallbacks",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/bridge/portal/sessions",
+        "createPortalSession",
+        "bridge",
+        "Create a credential-reference-backed authenticated portal session.",
+        "picux.createPortalSession",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/bridge/portal/sessions",
+        "listPortalSessions",
+        "bridge",
+        "List authenticated portal sessions.",
+        "picux.listPortalSessions",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/bridge/portal/sessions/{portalSessionId}",
+        "getPortalSession",
+        "bridge",
+        "Fetch an authenticated portal session.",
+        "picux.getPortalSession",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/bridge/portal/sessions/{portalSessionId}/preflight",
+        "preflightPortalSession",
+        "bridge",
+        "Check portal session credential, MFA, and target-scope readiness before authenticated browser work starts.",
+        "picux.preflightPortalSession",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/bridge/portal/actions",
+        "createPortalAction",
+        "bridge",
+        "Create an authenticated portal action for record retrieval, form submission, or recovery steps.",
+        "picux.createPortalAction",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/bridge/portal/actions",
+        "listPortalActions",
+        "bridge",
+        "List authenticated portal actions.",
+        "picux.listPortalActions",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/bridge/portal/actions/{portalActionId}",
+        "getPortalAction",
+        "bridge",
+        "Fetch an authenticated portal action.",
+        "picux.getPortalAction",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/bridge/portal/templates",
+        "listPortalActionTemplates",
+        "bridge",
+        "List reusable authenticated portal action templates.",
+        "picux.listPortalActionTemplates",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/bridge/portal/templates/{templateId}",
+        "getPortalActionTemplate",
+        "bridge",
+        "Fetch a reusable authenticated portal action template.",
+        "picux.getPortalActionTemplate",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/bridge/portal/playbooks",
+        "listPortalPlaybooks",
+        "bridge",
+        "List merchant, carrier, and utility portal recovery playbooks.",
+        "picux.listPortalPlaybooks",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/bridge/portal/playbooks/{playbookId}",
+        "getPortalPlaybook",
+        "bridge",
+        "Fetch a portal recovery playbook.",
+        "picux.getPortalPlaybook",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/bridge/portal/playbooks/{playbookId}/instantiate",
+        "instantiatePortalPlaybook",
+        "bridge",
+        "Instantiate a portal recovery playbook into queued portal actions.",
+        "picux.instantiatePortalPlaybook",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/bridge/portal/actions/{portalActionId}/run",
+        "runPortalAction",
+        "bridge",
+        "Run an authenticated portal action through the PortalBrowser tool.",
+        "picux.runPortalAction",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/bridge/connectors/match",
+        "matchConnectors",
+        "bridge",
+        "Match BRIDGE connectors by capability and credential scope.",
+        "picux.matchConnectors",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/bridge/connectors/{connectorId}/preflight",
+        "preflightConnector",
+        "bridge",
+        "Preflight a BRIDGE connector action with policy, scope, and secret checks.",
+        "picux.preflightConnector",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/bridge/connectors/{connectorId}/update",
+        "updateConnector",
+        "bridge",
+        "Update BRIDGE connector status or scope metadata.",
+        "picux.updateConnector",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/proxy/missions",
+        "listProxyMissions",
+        "proxy",
+        "List PROXY human-in-the-loop missions.",
+        "picux.listProxyMissions",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/proxy/missions/{proxyId}",
+        "getProxyMission",
+        "proxy",
+        "Fetch a PROXY human-in-the-loop mission.",
+        "picux.proxyGet",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/proxy/missions",
+        "createProxyMission",
+        "proxy",
+        "Request human intervention and suspend RESOLVE until PROXY returns an outcome.",
+        "picux.proxyRequest",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/proxy/missions/{proxyId}/outcome",
+        "submitProxyMissionOutcome",
+        "proxy",
+        "Submit a PROXY outcome for a known mission.",
+        "picux.proxySubmitMissionOutcome",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/proxy/outcomes",
+        "submitProxyOutcome",
+        "proxy",
+        "Submit a PROXY outcome by proxy, request, provider, or connector callback reference.",
+        "picux.proxySubmitOutcome",
+    ),
+    ContractEndpoint("GET", "/v1/tasks", "listTasks", "tasks", "List Picux protocol tasks.", "picux.listTasks"),
+    ContractEndpoint("GET", "/v1/tasks/{taskId}", "getTask", "tasks", "Fetch a Picux protocol task.", "picux.getTask"),
+    ContractEndpoint("POST", "/v1/tasks", "createTask", "tasks", "Create a Picux protocol task.", "picux.createTask"),
+    ContractEndpoint("POST", "/v1/tasks/{taskId}/update", "updateTask", "tasks", "Update a Picux protocol task.", "picux.updateTask"),
+    ContractEndpoint("GET", "/v1/cases", "listCases", "cases", "List formal Picux case workspaces.", "picux.listCases"),
+    ContractEndpoint("POST", "/v1/cases", "createCase", "cases", "Create or upsert a formal Picux case workspace.", "picux.createCase"),
+    ContractEndpoint("GET", "/v1/cases/{caseId}", "getCase", "cases", "Fetch a formal Picux case workspace.", "picux.getCase"),
+    ContractEndpoint("POST", "/v1/cases/{caseId}/update", "updateCase", "cases", "Update case workspace status, metadata, or collaboration state.", "picux.updateCase"),
+    ContractEndpoint("POST", "/v1/cases/{caseId}/stakeholders", "addCaseStakeholder", "cases", "Add a stakeholder to a case workspace.", "picux.addCaseStakeholder"),
+    ContractEndpoint("POST", "/v1/cases/{caseId}/deadlines", "addCaseDeadline", "cases", "Add a deadline to a case workspace.", "picux.addCaseDeadline"),
+    ContractEndpoint("POST", "/v1/cases/{caseId}/deadlines/review", "reviewCaseDeadlines", "cases", "Review case deadlines and mark overdue open deadlines as missed.", "picux.reviewCaseDeadlines"),
+    ContractEndpoint("POST", "/v1/cases/{caseId}/actions", "addCaseAction", "cases", "Add a stakeholder-oriented action item to a case workspace.", "picux.addCaseAction"),
+    ContractEndpoint("GET", "/v1/cases/{caseId}/actions", "listCaseActions", "cases", "List stakeholder-oriented action items for a case workspace.", "picux.listCaseActions"),
+    ContractEndpoint("POST", "/v1/cases/{caseId}/actions/{actionId}/update", "updateCaseAction", "cases", "Update a case action item status, owner, due date, or refs.", "picux.updateCaseAction"),
+    ContractEndpoint("POST", "/v1/cases/{caseId}/events", "addCaseEvent", "cases", "Append a status timeline event to a case workspace.", "picux.addCaseEvent"),
+    ContractEndpoint("GET", "/v1/cases/{caseId}/timeline", "caseTimeline", "cases", "Fetch a case workspace status timeline.", "picux.caseTimeline"),
+    ContractEndpoint("POST", "/v1/cases/{caseId}/evidence", "addCaseEvidence", "cases", "Attach evidence references to a case workspace.", "picux.addCaseEvidence"),
+    ContractEndpoint("POST", "/v1/cases/{caseId}/notes", "addCaseNote", "cases", "Add a collaboration note to a case workspace.", "picux.addCaseNote"),
+    ContractEndpoint("GET", "/v1/cases/{caseId}/notes", "listCaseNotes", "cases", "List collaboration notes for a case workspace.", "picux.listCaseNotes"),
+    ContractEndpoint("POST", "/v1/cases/{caseId}/export", "exportCaseBundle", "cases", "Export a portable evidence bundle for a case workspace.", "picux.exportCaseBundle"),
+    ContractEndpoint("GET", "/v1/workflows/templates", "listWorkflowTemplates", "workflows", "List Picux flagship workflow templates.", "picux.listWorkflowTemplates"),
+    ContractEndpoint("GET", "/v1/workflows/templates/{templateId}", "getWorkflowTemplate", "workflows", "Fetch a Picux workflow template.", "picux.getWorkflowTemplate"),
+    ContractEndpoint("POST", "/v1/workflows/templates/{templateId}/run", "runWorkflowTemplate", "workflows", "Run a Picux workflow template.", "picux.runWorkflowTemplate"),
+    ContractEndpoint("POST", "/v1/hunt/discover", "huntDiscover", "hunt", "Discover and rank HUNT telemetry.", "picux.huntDiscover"),
+    ContractEndpoint("POST", "/v1/resolve/scamTriage", "resolveScamTriage", "resolve", "Run Resolve scam and dispute triage.", "picux.resolveScamTriage"),
+    ContractEndpoint(
+        "POST",
+        "/v1/tasks/{taskId}/resolve",
+        "resolveTask",
+        "resolve",
+        "Resolve evidence for a Picux task.",
+        "picux.resolveTask",
+    ),
+    ContractEndpoint("GET", "/v1/mandates", "listMandates", "mandates", "List Picux mandate records.", "picux.listMandates"),
+    ContractEndpoint("GET", "/v1/mandates/{mandateId}", "getMandate", "mandates", "Fetch a Picux mandate record.", "picux.getMandate"),
+    ContractEndpoint("POST", "/v1/mandates", "createMandate", "mandates", "Register a Picux mandate.", "picux.createMandate"),
+    ContractEndpoint(
+        "POST",
+        "/v1/mandates/{mandateId}/verify",
+        "verifyMandate",
+        "mandates",
+        "Verify a Picux mandate.",
+        "picux.verifyMandate",
+    ),
+    ContractEndpoint("GET", "/v1/pay/rails", "listPayRails", "pay", "List Picux PAY machine-payment rails.", "picux.listPayRails"),
+    ContractEndpoint("GET", "/v1/pay/rails/{railId}", "getPayRail", "pay", "Fetch a Picux PAY machine-payment rail.", "picux.getPayRail"),
+    ContractEndpoint(
+        "POST",
+        "/v1/pay/challenges",
+        "createPaymentChallenge",
+        "pay",
+        "Create a machine-payment challenge for a protected resource.",
+        "picux.createPaymentChallenge",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/pay/challenges/{challengeId}/verify",
+        "verifyPaymentChallenge",
+        "pay",
+        "Verify a machine-payment credential for a PAY challenge.",
+        "picux.verifyPaymentChallenge",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/pay/sessions",
+        "createPaymentSession",
+        "pay",
+        "Create a bounded machine-payment session.",
+        "picux.createPaymentSession",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/pay/sessions/{sessionId}/authorize",
+        "authorizePaymentSession",
+        "pay",
+        "Authorize a machine-payment session.",
+        "picux.authorizePaymentSession",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/pay/sessions/{sessionId}/consume",
+        "consumePaymentSession",
+        "pay",
+        "Record usage against a machine-payment session.",
+        "picux.consumePaymentSession",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/pay/sessions/{sessionId}/close",
+        "closePaymentSession",
+        "pay",
+        "Close a machine-payment session.",
+        "picux.closePaymentSession",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/pay/local/resources/{resourceId}",
+        "runLocalPaidResource",
+        "pay",
+        "Run a local paid resource through the Picux PAY 402 loop.",
+        "picux.runLocalPaidResource",
+    ),
+    ContractEndpoint("POST", "/v1/pay/escrows", "createEscrow", "pay", "Create a Picux PAY escrow.", "picux.createEscrow"),
+    ContractEndpoint("GET", "/v1/pay/escrows", "listEscrows", "pay", "List Picux PAY escrow records.", "picux.listEscrows"),
+    ContractEndpoint(
+        "GET",
+        "/v1/pay/escrows/{escrowId}",
+        "getEscrow",
+        "pay",
+        "Fetch a Picux PAY escrow record.",
+        "picux.getEscrow",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/pay/escrows/{escrowId}/update",
+        "updateEscrow",
+        "pay",
+        "Update a Picux PAY escrow record.",
+        "picux.updateEscrow",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/pay/escrows/{escrowId}/fund",
+        "fundEscrow",
+        "pay",
+        "Mark a Picux PAY escrow as funded.",
+        "picux.fundEscrow",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/pay/escrows/{escrowId}/proof",
+        "submitEscrowProof",
+        "pay",
+        "Attach proof-of-utility evidence to a Picux PAY escrow.",
+        "picux.submitEscrowProof",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/pay/escrows/{escrowId}/settle",
+        "settleEscrow",
+        "pay",
+        "Settle a Picux PAY escrow after proof verification.",
+        "picux.settleEscrow",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/pay/escrows/{escrowId}/refund",
+        "refundEscrow",
+        "pay",
+        "Refund a Picux PAY escrow.",
+        "picux.refundEscrow",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/pay/escrows/{escrowId}/dispute",
+        "disputeEscrow",
+        "pay",
+        "Open a dispute against a Picux PAY escrow.",
+        "picux.disputeEscrow",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/pay/adapters/contract",
+        "settlementAdapterContract",
+        "pay",
+        "Return the Picux PAY settlement adapter contract.",
+        "picux.settlementAdapterContract",
+    ),
+    ContractEndpoint("GET", "/v1/pay/adapters", "listPayAdapters", "pay", "List Picux PAY rail adapter scaffolds.", "picux.listPayAdapters"),
+    ContractEndpoint("GET", "/v1/pay/adapters/{adapterId}", "getPayAdapter", "pay", "Fetch a Picux PAY rail adapter scaffold.", "picux.getPayAdapter"),
+    ContractEndpoint(
+        "POST",
+        "/v1/pay/adapters/{adapterId}/invoke",
+        "invokePayAdapter",
+        "pay",
+        "Invoke a concrete Picux PAY rail adapter action.",
+        "picux.invokePayAdapter",
+    ),
+    ContractEndpoint("GET", "/v1/pay/reputation", "listReputationCards", "pay", "List PAY reputation cards.", "picux.listReputationCards"),
+    ContractEndpoint("GET", "/v1/pay/reputation/{cardId}", "getReputationCard", "pay", "Fetch a PAY reputation card.", "picux.getReputationCard"),
+    ContractEndpoint("POST", "/v1/pay/reputation", "updateReputationCard", "pay", "Update a PAY reputation card.", "picux.updateReputationCard"),
+    ContractEndpoint(
+        "POST",
+        "/v1/pay/prepare",
+        "prepareSettlement",
+        "pay",
+        "Prepare a PAY settlement instruction for an external adapter.",
+        "picux.prepareSettlement",
+    ),
+    ContractEndpoint("POST", "/v1/pay/settle", "settle", "pay", "Settle a Picux PAY request.", "picux.settle"),
+    ContractEndpoint("GET", "/v1/receipts", "listReceipts", "pay", "List settlement receipts.", "picux.listReceipts"),
+    ContractEndpoint(
+        "GET",
+        "/v1/receipts/{receiptId}",
+        "getReceipt",
+        "pay",
+        "Fetch a settlement receipt.",
+        "picux.getReceipt",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/audit/proofPacks/{packId}",
+        "getProofPack",
+        "audit",
+        "Fetch a portable proof pack.",
+        "picux.getProofPack",
+    ),
+    ContractEndpoint("GET", "/v1/audit/proofPacks", "listProofPacks", "audit", "List portable proof packs.", "picux.listProofPacks"),
+    ContractEndpoint(
+        "POST",
+        "/v1/audit/proofPacks",
+        "createProofPack",
+        "audit",
+        "Create a shareable proof pack from evidence, decisions, and outcomes.",
+        "picux.createProofPack",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/audit/evidence/{artifactId}",
+        "getEvidence",
+        "audit",
+        "Fetch a recorded evidence artifact.",
+        "picux.getEvidence",
+    ),
+    ContractEndpoint("GET", "/v1/audit/evidence", "listEvidence", "audit", "List evidence artifacts.", "picux.listEvidence"),
+    ContractEndpoint(
+        "GET",
+        "/v1/audit/pov/{povId}",
+        "getPov",
+        "audit",
+        "Fetch a proof-of-value record.",
+        "picux.getPov",
+    ),
+    ContractEndpoint("GET", "/v1/audit/pov", "listPov", "audit", "List proof-of-value records.", "picux.listPov"),
+    ContractEndpoint(
+        "POST",
+        "/v1/audit/evidence",
+        "recordEvidence",
+        "audit",
+        "Record a content-addressed evidence artifact.",
+        "picux.recordEvidence",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/audit/pov",
+        "recordPov",
+        "audit",
+        "Record a proof-of-value chain entry.",
+        "picux.recordPov",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/audit/receipts/verify",
+        "verifyReceipt",
+        "audit",
+        "Verify a PAY receipt against proof-of-value.",
+        "picux.verifyReceipt",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/audit/chain/verify",
+        "verifyChain",
+        "audit",
+        "Verify proof-of-value chain continuity.",
+        "picux.verifyChain",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/signals/community",
+        "listCommunitySignals",
+        "signals",
+        "List durable community signal records.",
+        "picux.listCommunitySignals",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/signals/community/{signalId}",
+        "getCommunitySignal",
+        "signals",
+        "Fetch a durable community signal record.",
+        "picux.getCommunitySignal",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/signals/community",
+        "communitySignal",
+        "signals",
+        "Ingest a community signal.",
+        "picux.communitySignal",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/signals/community/analyze",
+        "analyzeCommunitySignal",
+        "signals",
+        "Analyze a community signal.",
+        "picux.analyzeCommunitySignal",
+    ),
+    ContractEndpoint(
+        "POST",
+        "/v1/signals/community/launch-task",
+        "launchCommunityTask",
+        "signals",
+        "Launch an approval-gated task from a community signal.",
+        "picux.launchCommunityTask",
+    ),
+    ContractEndpoint(
+        "GET",
+        "/v1/signals/community/entities",
+        "communityEntities",
+        "signals",
+        "List community signal entities.",
+        "picux.communityEntities",
+    ),
+)