@pyxmate/memory 1.13.0 → 1.15.0

package/dist/data-plane-contract.d.ts

@@ -0,0 +1,234 @@
+declare const DATA_PLANE_CONTRACT_VERSION: "pyx-data-plane-contract-v1";
+declare const DATA_PLANE_CATALOG_VERSION: "maas-request-v1";
+declare const DATA_PLANE_MANIFEST_VERSION: "pyx-data-plane-manifest-v1";
+declare const DATA_PLANE_STEP_INPUT_FRAME: "pyx-data-plane-step-input-v1\0";
+declare const DATA_PLANE_MANIFEST_FRAME: "pyx-data-plane-manifest-v1\0";
+declare const DATA_PLANE_HTTP_RESPONSE_FRAME: "pyx-data-plane-http-response-v1\0";
+declare const DATA_PLANE_COMPILER_LIMITS: {
+    readonly operationIdBytes: 64;
+    readonly identityBytes: 256;
+    readonly semanticTextBytes: 128000;
+    readonly canonicalInputBytes: 1048576;
+    readonly profileContentBytes: 8192;
+};
+declare const SENSITIVITY_LEVELS: readonly ["public", "internal", "secret"];
+declare const PRINCIPAL_KINDS: readonly ["api_key", "user"];
+declare const TENANT_MODES: readonly ["single", "multi"];
+type SensitivityLevel = (typeof SENSITIVITY_LEVELS)[number];
+type CanonicalPrimitive = null | boolean | number | string;
+type CanonicalDataPlaneValue = CanonicalPrimitive | readonly CanonicalDataPlaneValue[] | {
+    readonly [key: string]: CanonicalDataPlaneValue;
+};
+type CanonicalDataPlaneObject = {
+    readonly [key: string]: CanonicalDataPlaneValue;
+};
+interface CompileContext {
+    organizationId: string;
+    projectId: string;
+    instanceId: string;
+    operationId: string;
+    principal: {
+        kind: (typeof PRINCIPAL_KINDS)[number];
+        id: string;
+    };
+    scope: {
+        tenantId: string;
+        namespaceId?: string;
+        userId?: string;
+        teamId?: string;
+        callerAccessLevel?: SensitivityLevel;
+    };
+    resolvedAt: string;
+    runtimeAttestation: {
+        contractVersion: typeof DATA_PLANE_CONTRACT_VERSION;
+        tenantMode: (typeof TENANT_MODES)[number];
+        defaultAgentId: string | null;
+        effectiveSource: string;
+        sharedFallback: boolean;
+        sqliteAtomicOneStep: true;
+    };
+}
+interface CompiledDataPlaneExecutionPlan {
+    mode: 'journal';
+    version: typeof DATA_PLANE_MANIFEST_VERSION;
+    steps: readonly {
+        sequence: number;
+        stepKey: string;
+        kind: 'sqlite' | 'vector' | 'graph' | 'embedding';
+        execution: 'sqlite_atomic' | 'idempotent_adapter';
+        inputSha256: string;
+    }[];
+}
+interface CompileDataPlaneRequest {
+    catalogVersion: typeof DATA_PLANE_CATALOG_VERSION;
+    operation: DataPlaneCatalogOperation;
+    context: CompileContext;
+    input: unknown;
+}
+type DataPlaneUnsupportedReasonCode = 'embedding_execution_not_ready' | 'multi_step_execution_not_ready' | 'fanout_execution_not_ready' | 'graph_execution_not_ready' | 'corpus_dependent_execution_not_ready' | 'external_io_execution_not_ready' | 'nonchargeable_operation';
+interface SupportedCatalogEntry {
+    support: 'sqlite_atomic_one_step' | 'journal_multi_step';
+}
+declare const DATA_PLANE_OPERATION_COVERAGE: {
+    readonly 'rest:store': {
+        readonly support: "journal_multi_step";
+    };
+    readonly 'rest:search': {
+        readonly support: "journal_multi_step";
+    };
+    readonly 'rest:query_as_of': {
+        readonly support: "sqlite_atomic_one_step";
+    };
+    readonly 'rest:query_by_event_time': {
+        readonly support: "sqlite_atomic_one_step";
+    };
+    readonly 'rest:log': {
+        readonly support: "sqlite_atomic_one_step";
+    };
+    readonly 'rest:lineage': {
+        readonly support: "journal_multi_step";
+    };
+    readonly 'rest:reinforce': {
+        readonly support: "journal_multi_step";
+    };
+    readonly 'rest:record_correction': {
+        readonly support: "sqlite_atomic_one_step";
+    };
+    readonly 'rest:fetch_corrections': {
+        readonly support: "sqlite_atomic_one_step";
+    };
+    readonly 'rest:synthesis_entity_refresh': {
+        readonly support: "not_execution_ready";
+        readonly reasonCode: "external_io_execution_not_ready";
+        readonly reason: "entity synthesis refresh invokes an external LLM with data-dependent output and is not execution-ready in data-plane contract v1";
+    };
+    readonly 'rest:get_synthesis_entity': {
+        readonly support: "sqlite_atomic_one_step";
+    };
+    readonly 'rest:list': {
+        readonly support: "sqlite_atomic_one_step";
+    };
+    readonly 'rest:batch_store': {
+        readonly support: "journal_multi_step";
+    };
+    readonly 'rest:get': {
+        readonly support: "sqlite_atomic_one_step";
+    };
+    readonly 'rest:delete': {
+        readonly support: "journal_multi_step";
+    };
+    readonly 'rest:graph_nodes': {
+        readonly support: "journal_multi_step";
+    };
+    readonly 'rest:graph_relationships': {
+        readonly support: "journal_multi_step";
+    };
+    readonly 'rest:graph_subgraph': {
+        readonly support: "journal_multi_step";
+    };
+    readonly 'rest:embedding_map': {
+        readonly support: "not_execution_ready";
+        readonly reasonCode: "corpus_dependent_execution_not_ready";
+        readonly reason: "embedding map reads cache state and may compute PCA over a data-dependent corpus, so it is not execution-ready in data-plane contract v1";
+    };
+    readonly 'mcp:search_memories': {
+        readonly support: "journal_multi_step";
+    };
+    readonly 'mcp:store_memory': {
+        readonly support: "journal_multi_step";
+    };
+    readonly 'mcp:get_memory': {
+        readonly support: "sqlite_atomic_one_step";
+    };
+    readonly 'mcp:lineage': {
+        readonly support: "journal_multi_step";
+    };
+    readonly 'mcp:reinforce': {
+        readonly support: "journal_multi_step";
+    };
+    readonly 'mcp:list_memories': {
+        readonly support: "sqlite_atomic_one_step";
+    };
+    readonly 'mcp:delete_memory': {
+        readonly support: "journal_multi_step";
+    };
+    readonly 'mcp:ingest_memory_file': {
+        readonly support: "not_execution_ready";
+        readonly reasonCode: "external_io_execution_not_ready";
+        readonly reason: "ingest_memory_file reads caller-local files and is not execution-ready in data-plane contract v1";
+    };
+    readonly 'mcp:summarize_memory_entity': {
+        readonly support: "sqlite_atomic_one_step";
+    };
+    readonly 'mcp:get_taxonomy_state': {
+        readonly support: "journal_multi_step";
+    };
+    readonly 'mcp:name_cluster': {
+        readonly support: "journal_multi_step";
+    };
+    readonly 'mcp:status': {
+        readonly support: "not_execution_ready";
+        readonly reasonCode: "nonchargeable_operation";
+        readonly reason: "status is nonchargeable and must bypass data-plane reservation";
+    };
+    readonly 'mcp:get_user_profile': {
+        readonly support: "sqlite_atomic_one_step";
+    };
+    readonly 'mcp:upsert_user_profile': {
+        readonly support: "sqlite_atomic_one_step";
+    };
+    readonly 'mcp:record_correction': {
+        readonly support: "sqlite_atomic_one_step";
+    };
+    readonly 'mcp:fetch_applicable_corrections': {
+        readonly support: "sqlite_atomic_one_step";
+    };
+    readonly 'mcp:fetch_due_facts': {
+        readonly support: "sqlite_atomic_one_step";
+    };
+};
+type DataPlaneCatalogOperation = keyof typeof DATA_PLANE_OPERATION_COVERAGE;
+type SupportedDataPlaneCatalogOperation = {
+    [Operation in DataPlaneCatalogOperation]: (typeof DATA_PLANE_OPERATION_COVERAGE)[Operation] extends SupportedCatalogEntry ? Operation : never;
+}[DataPlaneCatalogOperation];
+type CompileDataPlaneResult = {
+    kind: 'unsupported';
+    catalogVersion: typeof DATA_PLANE_CATALOG_VERSION;
+    operation: DataPlaneCatalogOperation;
+    reasonCode: DataPlaneUnsupportedReasonCode;
+    reason: string;
+} | {
+    kind: 'compiled';
+    contractVersion: typeof DATA_PLANE_CONTRACT_VERSION;
+    catalogVersion: typeof DATA_PLANE_CATALOG_VERSION;
+    operation: SupportedDataPlaneCatalogOperation;
+    context: CompileContext;
+    normalizedInput: CanonicalDataPlaneObject;
+    stepInputCanonicalJson: string;
+    stepInputSha256: string;
+    executionPlan: CompiledDataPlaneExecutionPlan;
+    manifestCanonicalJson: string;
+    manifestSha256: string;
+    quoteDimensions: {
+        databaseOperations: number;
+        embeddingUnicodeScalars: number;
+        embeddingEvents: number;
+    };
+};
+declare function canonicalDataPlaneJson(value: unknown): string;
+declare function hashDataPlaneStepInputV1(value: unknown): {
+    canonicalJson: string;
+    sha256: string;
+};
+declare function hashDataPlaneManifestV1(value: unknown): {
+    canonicalJson: string;
+    sha256: string;
+};
+/**
+ * Hash the exact replayable HTTP metadata owned by the data-plane contract. Transport and
+ * security headers (CORS, HSTS, CSP) are intentionally middleware-owned and excluded.
+ */
+declare function hashDataPlaneHttpResponseV1(statusCode: number, contentType: string, body: Uint8Array): string;
+declare function compileDataPlaneRequest(request: CompileDataPlaneRequest): CompileDataPlaneResult;
+
+export { type CanonicalDataPlaneObject, type CanonicalDataPlaneValue, type CompileContext, type CompileDataPlaneRequest, type CompileDataPlaneResult, type CompiledDataPlaneExecutionPlan, DATA_PLANE_CATALOG_VERSION, DATA_PLANE_COMPILER_LIMITS, DATA_PLANE_CONTRACT_VERSION, DATA_PLANE_HTTP_RESPONSE_FRAME, DATA_PLANE_MANIFEST_FRAME, DATA_PLANE_MANIFEST_VERSION, DATA_PLANE_OPERATION_COVERAGE, DATA_PLANE_STEP_INPUT_FRAME, type DataPlaneCatalogOperation, type DataPlaneUnsupportedReasonCode, type SupportedDataPlaneCatalogOperation, canonicalDataPlaneJson, compileDataPlaneRequest, hashDataPlaneHttpResponseV1, hashDataPlaneManifestV1, hashDataPlaneStepInputV1 };