@retinue/agentkit 0.1.0 → 0.3.0

package/dist/testing/conformance/index.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Shared storage conformance suite — `docs/02` "Conformance suite", widened by #91.
+ *
+ * Every storage adapter must pass the same harnesses, so "swap the database" is a verified property
+ * rather than a claim. Before #91 this suite covered one port of nineteen, which is how #20
+ * ("PostgreSQL adapter") could satisfy its own acceptance criterion — *"passes the full conformance
+ * suite"* — with a single table implemented.
+ *
+ * An adapter package supplies factories; it writes no test bodies. Not part of the published build
+ * (`src/testing/**` is excluded in tsconfig); imported by tests only.
+ *
+ * `REGISTERED_PORTS` below is the coverage ledger the guard test in
+ * `src/__tests__/conformance-coverage.test.ts` checks, so a port cannot gain methods without also
+ * gaining a harness.
+ */
+export * from "./capability.js";
+export * from "./parents.js";
+export * from "./conversation-store.js";
+export * from "./run-store.js";
+export * from "./run-event-log.js";
+export * from "./checkpoint-store.js";
+export * from "./run-coordinator.js";
+export * from "./session-state.js";
+export * from "./records.js";
+export * from "./hitl.js";
+export * from "./files.js";
+export * from "./artifacts.js";
+export * from "./artifact-exports.js";
+export * from "./knowledge.js";
+export * from "./rollups.js";
+export * from "./usage-limits.js";
+export * from "./rate-limit.js";
+export * from "./connections.js";
+export * from "./evaluation.js";
+export * from "./invariants.js";
+/** A port with methods, and the harness that verifies it. */
+export type PortCoverage = {
+    readonly port: string;
+    readonly harness: string;
+};
+/**
+ * Ports that have methods and therefore must have a harness. Kept as data so the guard test can
+ * compare it against the interfaces actually exported by the port modules.
+ */
+export declare const REGISTERED_PORTS: readonly PortCoverage[];
+/**
+ * Registered ports whose harness is **not** required to assert cross-tenant isolation, with the
+ * reason. Everything else must: governing principle 1 says every tenant-sensitive operation receives
+ * an explicit tenant context, and the `AgentStore` leak #91 found proves the type system alone does
+ * not enforce it — a store can accept `TenantScope` and quietly ignore it.
+ *
+ * Keep this list as short as the truth allows. An entry here is a claim that the port has nothing
+ * tenant-scoped to leak, not that testing it would be inconvenient.
+ */
+export declare const ISOLATION_EXEMPT_PORTS: readonly {
+    readonly port: string;
+    readonly reason: string;
+}[];
+/**
+ * Method-less placeholder interfaces, deliberately without a harness. An empty harness would pass
+ * vacuously and read as coverage, so the guard test instead fails if one of these gains a method —
+ * turning "we forgot to widen the suite" into a build failure. Each lands with its own SPEC:
+ * `EvaluationStore` #141, `KnowledgeStore`/`VectorIndex`/`KeywordIndex` #135–#136, `ArtifactStore` #133.
+ *
+ * `FileMetadataStore` left this list in #129, which is the mechanism working as intended: it gained methods
+ * and the guard would have failed had a harness not come with them.
+ */
+/**
+ * Ports declared with no methods yet.
+ *
+ * Empty as of #141, and the list stays: the guard that fails when a placeholder gains methods without a harness
+ * is what stopped `KnowledgeStore` and `EvaluationStore` from quietly shipping untested, and deleting it once
+ * the list is empty would remove the check that catches the next one.
+ */
+export declare const PLACEHOLDER_PORTS: readonly string[];
+/**
+ * Infrastructure ports that are not storage. Their real adapters land with REQ-015 (#105 BullMQ
+ * dispatcher, #106 Redis lock), at which point they join `REGISTERED_PORTS`. Listed so the omission
+ * is recorded rather than silent.
+ */
+export declare const DEFERRED_INFRASTRUCTURE_PORTS: readonly string[];
+/**
+ * Exported interfaces in the scanned port modules that are not storage at all, so a storage
+ * conformance harness would be meaningless for them. Classified explicitly rather than filtered by
+ * a name pattern, so adding one is a decision someone made on purpose.
+ */
+export declare const NON_STORAGE_PORTS: readonly string[];
+/**
+ * The port modules the coverage guard scans. Every exported interface in these files must appear in
+ * exactly one of the four lists above; an unclassified one fails the guard, which is what forces a
+ * new port to come with a harness or an explicit, reasoned exemption.
+ */
+export declare const SCANNED_PORT_MODULES: readonly string[];
+/** The adapters the conformance matrix reports on. */
+export declare const MATRIX_ADAPTERS: readonly ["memory", "postgres", "supabase"];
+export type MatrixAdapter = (typeof MATRIX_ADAPTERS)[number];
+/**
+ * Which ports each adapter implements today, and — for each it does not — the SPEC that will add
+ * it. This is the data behind the matrix's `NOT-IMPLEMENTED` cell and behind AC-3 of #92.
+ *
+ * The distinction that matters: a **classified** absence (listed here with a tracking issue) is a
+ * known gap and is allowed; an **unclassified** absence (a registered port missing from both lists)
+ * is an omission and fails the build. Without that split, either the matrix is permanently red until
+ * #100 lands, or a forgotten adapter silently reads as covered — and #20 closing green against
+ * "passes the full conformance suite" is what the second failure mode looks like in practice.
+ */
+export type AdapterCoverage = {
+    readonly adapter: MatrixAdapter;
+    readonly implemented: readonly string[];
+    readonly notImplemented: readonly {
+        readonly port: string;
+        readonly trackedBy: string;
+    }[];
+    /**
+     * Ports this adapter should **never** implement, with the reason.
+     *
+     * Distinct from `notImplemented`, which means "not yet, tracked by an issue". #129 forced the
+     * distinction: `FileContentStore` holds file bytes, and a relational adapter storing them would be the
+     * base64-in-`jsonb` antipattern #102 rejected when it declined to make `blobs` a pointer table.
+     *
+     * Listing it as pending would be a lie the matrix repeats forever, and leaving it out would be an
+     * unclassified absence the guard rejects. So it is a third answer, with a reason — the same shape as
+     * `ISOLATION_EXEMPT_PORTS`, and kept as short as the truth allows.
+     */
+    readonly notApplicable?: readonly {
+        readonly port: string;
+        readonly reason: string;
+    }[];
+};
+/**
+ * Ports Supabase implements itself rather than inheriting from Postgres (#129).
+ *
+ * The first entry in this list is a real change to what "Supabase" means here: for nineteen ports it was
+ * Postgres under another name, asserted by object identity. File bytes break that, and they break it for a
+ * good reason rather than by drift — object storage is a different service. Named here so the alias test can
+ * assert identity for everything *except* these, instead of being relaxed to let any port off.
+ */
+export declare const SUPABASE_NATIVE: readonly string[];
+/**
+ * The ports `adapters/supabase/index.ts` aliases from the Postgres adapter — all of them as of #104.
+ *
+ * Derived from `REGISTERED_PORTS` rather than listed, now that the answer is "all", so a newly
+ * registered port cannot quietly become an unclassified Supabase gap. The alias identity itself is
+ * asserted per port in `supabase-conformance.test.ts`, which is what keeps this honest: if an alias
+ * were repointed to a second implementation, that test fails rather than this list going stale.
+ */
+/**
+ * Ports Supabase will never implement — #248.
+ *
+ * Read by all three columns (`implemented` via the alias derivation, `notImplemented`, `notApplicable`) so they
+ * cannot disagree. The alias derivation below defaults a new port to "aliased", and its own comment says a
+ * future exemption "has to be stated" — this is where.
+ */
+export declare const SUPABASE_NOT_APPLICABLE: readonly string[];
+export declare const ADAPTER_COVERAGE: readonly AdapterCoverage[];
+/**
+ * The harness sources the isolation guard reads. Listed explicitly rather than globbed so a harness
+ * file that is added but never wired in shows up as a missing harness rather than being skipped.
+ */
+export declare const HARNESS_MODULES: readonly string[];
+export * from "./graph.js";
+export * from "./flows.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/conformance/index.js

@@ -0,0 +1,321 @@
+/**
+ * Shared storage conformance suite — `docs/02` "Conformance suite", widened by #91.
+ *
+ * Every storage adapter must pass the same harnesses, so "swap the database" is a verified property
+ * rather than a claim. Before #91 this suite covered one port of nineteen, which is how #20
+ * ("PostgreSQL adapter") could satisfy its own acceptance criterion — *"passes the full conformance
+ * suite"* — with a single table implemented.
+ *
+ * An adapter package supplies factories; it writes no test bodies. Not part of the published build
+ * (`src/testing/**` is excluded in tsconfig); imported by tests only.
+ *
+ * `REGISTERED_PORTS` below is the coverage ledger the guard test in
+ * `src/__tests__/conformance-coverage.test.ts` checks, so a port cannot gain methods without also
+ * gaining a harness.
+ */
+export * from "./capability.js";
+export * from "./parents.js";
+export * from "./conversation-store.js";
+export * from "./run-store.js";
+export * from "./run-event-log.js";
+export * from "./checkpoint-store.js";
+export * from "./run-coordinator.js";
+export * from "./session-state.js";
+export * from "./records.js";
+export * from "./hitl.js";
+export * from "./files.js";
+export * from "./artifacts.js";
+export * from "./artifact-exports.js";
+export * from "./knowledge.js";
+export * from "./rollups.js";
+export * from "./usage-limits.js";
+export * from "./rate-limit.js";
+export * from "./connections.js";
+export * from "./evaluation.js";
+export * from "./invariants.js";
+/**
+ * Ports that have methods and therefore must have a harness. Kept as data so the guard test can
+ * compare it against the interfaces actually exported by the port modules.
+ */
+export const REGISTERED_PORTS = [
+    { port: "ConversationStore", harness: "conversationStoreConformance" },
+    // #187, #186. Both have harnesses, and both are tenant-scoped — a flow's definition and its execution are as
+    // much a tenant's data as a conversation is.
+    { port: "FlowDefinitionStore", harness: "flowDefinitionStoreConformance" },
+    { port: "FlowExecutionStore", harness: "flowExecutionStoreConformance" },
+    { port: "SessionStateStore", harness: "sessionStateStoreConformance" },
+    { port: "ConversationBindingStore", harness: "conversationBindingStoreConformance" },
+    { port: "ConversationRunCoordinator", harness: "conversationRunCoordinatorConformance" },
+    { port: "ThreadSummaryStore", harness: "threadSummaryStoreConformance" },
+    { port: "RunStore", harness: "runStoreConformance" },
+    { port: "MessageStore", harness: "messageStoreConformance" },
+    { port: "AgentStore", harness: "agentStoreConformance" },
+    { port: "SkillStore", harness: "skillStoreConformance" },
+    /**
+     * #248. Not storage in the matrix sense — it is a counter, and its real adapter is Redis, so it has no
+     * Postgres or Supabase implementation and never will. Registered anyway because it *has* methods and a
+     * contract worth holding: the harness runs against the in-memory store and against a real Redis.
+     */
+    { port: "RateLimitStore", harness: "rateLimitStoreConformance" },
+    /** #261. Tenant-scoped storage like any other, holding a sealed blob it cannot read. */
+    { port: "ConnectionStore", harness: "connectionStoreConformance" },
+    { port: "InteractionStore", harness: "interactionStoreConformance" },
+    { port: "ApprovalGrantStore", harness: "approvalGrantStoreConformance" },
+    { port: "CheckpointStore", harness: "checkpointStoreConformance" },
+    { port: "UsageStore", harness: "usageStoreConformance" },
+    { port: "BlobStore", harness: "blobStoreConformance" },
+    { port: "UnitOfWork", harness: "unitOfWorkConformance" },
+    { port: "RunEventLog", harness: "runEventLogConformance" },
+    { port: "IdempotencyStore", harness: "idempotencyStoreConformance" },
+    { port: "PrincipalMemoryStore", harness: "principalMemoryStoreConformance" },
+    { port: "McpConnectionStore", harness: "mcpConnectionStoreConformance" },
+    { port: "FileMetadataStore", harness: "fileMetadataStoreConformance" },
+    { port: "FileContentStore", harness: "fileContentStoreConformance" },
+    { port: "ArtifactStore", harness: "artifactStoreConformance" },
+    { port: "ArtifactExportStore", harness: "artifactExportStoreConformance" },
+    { port: "KnowledgeStore", harness: "knowledgeStoreConformance" },
+    { port: "VectorIndex", harness: "vectorIndexConformance" },
+    { port: "KeywordIndex", harness: "keywordIndexConformance" },
+    /** #271. Ordinary rows, so it needs no pgvector — a deployment without the extension still runs graph-local. */
+    { port: "GraphStore", harness: "graphStoreConformance" },
+    { port: "UsageRollupStore", harness: "usageRollupStoreConformance" },
+    { port: "UsageLimitStore", harness: "usageLimitStoreConformance" },
+    { port: "EvaluationStore", harness: "evaluationStoreConformance" },
+];
+/**
+ * Registered ports whose harness is **not** required to assert cross-tenant isolation, with the
+ * reason. Everything else must: governing principle 1 says every tenant-sensitive operation receives
+ * an explicit tenant context, and the `AgentStore` leak #91 found proves the type system alone does
+ * not enforce it — a store can accept `TenantScope` and quietly ignore it.
+ *
+ * Keep this list as short as the truth allows. An entry here is a claim that the port has nothing
+ * tenant-scoped to leak, not that testing it would be inconvenient.
+ */
+export const ISOLATION_EXEMPT_PORTS = [
+    {
+        port: "UnitOfWork",
+        reason: "run<T>(fn) takes no tenant parameter and holds no data of its own, so there is nothing " +
+            "tenant-scoped to isolate. The stores it wraps are each covered by their own harness.",
+    },
+];
+/**
+ * Method-less placeholder interfaces, deliberately without a harness. An empty harness would pass
+ * vacuously and read as coverage, so the guard test instead fails if one of these gains a method —
+ * turning "we forgot to widen the suite" into a build failure. Each lands with its own SPEC:
+ * `EvaluationStore` #141, `KnowledgeStore`/`VectorIndex`/`KeywordIndex` #135–#136, `ArtifactStore` #133.
+ *
+ * `FileMetadataStore` left this list in #129, which is the mechanism working as intended: it gained methods
+ * and the guard would have failed had a harness not come with them.
+ */
+/**
+ * Ports declared with no methods yet.
+ *
+ * Empty as of #141, and the list stays: the guard that fails when a placeholder gains methods without a harness
+ * is what stopped `KnowledgeStore` and `EvaluationStore` from quietly shipping untested, and deleting it once
+ * the list is empty would remove the check that catches the next one.
+ */
+export const PLACEHOLDER_PORTS = [];
+/**
+ * Infrastructure ports that are not storage. Their real adapters land with REQ-015 (#105 BullMQ
+ * dispatcher, #106 Redis lock), at which point they join `REGISTERED_PORTS`. Listed so the omission
+ * is recorded rather than silent.
+ */
+export const DEFERRED_INFRASTRUCTURE_PORTS = ["JobDispatcher", "DistributedLockStore"];
+/**
+ * Exported interfaces in the scanned port modules that are not storage at all, so a storage
+ * conformance harness would be meaningless for them. Classified explicitly rather than filtered by
+ * a name pattern, so adding one is a decision someone made on purpose.
+ */
+export const NON_STORAGE_PORTS = [
+    "CapabilityAware", // adapter self-description, consumed *by* the suite
+    "RealtimePublisher", // fan-out transport, not durable storage
+    "McpClient", // outbound protocol client
+    "RateLimitObserver", // a refusal sink, like QuotaObserver — nothing durable to verify
+];
+/**
+ * The port modules the coverage guard scans. Every exported interface in these files must appear in
+ * exactly one of the four lists above; an unclassified one fails the guard, which is what forces a
+ * new port to come with a harness or an explicit, reasoned exemption.
+ */
+export const SCANNED_PORT_MODULES = [
+    "src/persistence/index.ts",
+    "src/core/events.ts",
+    "src/idempotency/index.ts",
+    "src/principal-memory/index.ts",
+    "src/mcp/provider.ts",
+    "src/runtime/index.ts",
+    // Added by #248. A port declared in a module nobody scans escapes this ledger entirely, which is how
+    // `RateLimitStore` would have shipped with no coverage record at all — the omission being invisible rather
+    // than listed is exactly what `PLACEHOLDER_PORTS` and `DEFERRED_INFRASTRUCTURE_PORTS` exist to prevent.
+    "src/usage/rate-limit.ts",
+    // #261.
+    "src/connections/index.ts",
+];
+/** The adapters the conformance matrix reports on. */
+export const MATRIX_ADAPTERS = ["memory", "postgres", "supabase"];
+/**
+ * Why the **relational** adapter does not implement `FileContentStore`.
+ *
+ * Postgres alone. Supabase has a real home for file bytes — Supabase Storage, `adapters/supabase/storage.ts`
+ * — so claiming an exemption there would be claiming a gap that does not exist. The exemption is about the
+ * relational column, not about the deployment.
+ */
+const RELATIONAL_CONTENT_EXEMPTION = {
+    port: "FileContentStore",
+    reason: "File bytes belong in object storage. A relational adapter holding them means base64 in a column — the " +
+        "antipattern #102 rejected when it declined to make `blobs` a pointer table, and the reason #129 split " +
+        "metadata from content in the first place. Object-storage adapters implement this port instead.",
+};
+/**
+ * Ports Supabase implements itself rather than inheriting from Postgres (#129).
+ *
+ * The first entry in this list is a real change to what "Supabase" means here: for nineteen ports it was
+ * Postgres under another name, asserted by object identity. File bytes break that, and they break it for a
+ * good reason rather than by drift — object storage is a different service. Named here so the alias test can
+ * assert identity for everything *except* these, instead of being relaxed to let any port off.
+ */
+export const SUPABASE_NATIVE = ["FileContentStore"];
+/**
+ * The ports `adapters/supabase/index.ts` aliases from the Postgres adapter — all of them as of #104.
+ *
+ * Derived from `REGISTERED_PORTS` rather than listed, now that the answer is "all", so a newly
+ * registered port cannot quietly become an unclassified Supabase gap. The alias identity itself is
+ * asserted per port in `supabase-conformance.test.ts`, which is what keeps this honest: if an alias
+ * were repointed to a second implementation, that test fails rather than this list going stale.
+ */
+/**
+ * Ports Supabase will never implement — #248.
+ *
+ * Read by all three columns (`implemented` via the alias derivation, `notImplemented`, `notApplicable`) so they
+ * cannot disagree. The alias derivation below defaults a new port to "aliased", and its own comment says a
+ * future exemption "has to be stated" — this is where.
+ */
+export const SUPABASE_NOT_APPLICABLE = ["RateLimitStore"];
+const SUPABASE_ALIASED = REGISTERED_PORTS.map((p) => p.port).filter(
+// `FileContentStore` is the one registered port the Postgres adapter does not implement, so there is
+// nothing for Supabase to alias. Filtered from the derivation rather than removed from it, so a future
+// port still defaults to "aliased" and a future exemption has to be stated.
+(port) => !SUPABASE_NATIVE.includes(port) && !SUPABASE_NOT_APPLICABLE.includes(port));
+/** Ports with no Postgres store yet, each against the SPEC that adds it (REQ-010→013). */
+const POSTGRES_PENDING = [];
+export const ADAPTER_COVERAGE = [
+    {
+        adapter: "memory",
+        // The reference implementation: it implements every port, which is what makes it the baseline
+        // the other adapters are compared against.
+        implemented: REGISTERED_PORTS.map((p) => p.port),
+        notImplemented: [],
+    },
+    {
+        adapter: "postgres",
+        implemented: [
+            "ConversationStore",
+            // #261 — the store holds a sealed blob it cannot read.
+            "ConnectionStore",
+            // #187, #186 — both harnesses run against the Postgres adapter in `postgres-conformance.test.ts`.
+            "FlowDefinitionStore",
+            "FlowExecutionStore",
+            "RunStore",
+            "RunEventLog",
+            "CheckpointStore",
+            "MessageStore",
+            "AgentStore",
+            "ConversationBindingStore",
+            "SessionStateStore",
+            "ThreadSummaryStore",
+            "ConversationRunCoordinator",
+            "UnitOfWork",
+            "InteractionStore",
+            "ApprovalGrantStore",
+            "UsageStore",
+            "IdempotencyStore",
+            "SkillStore",
+            "McpConnectionStore",
+            "PrincipalMemoryStore",
+            "BlobStore",
+            "FileMetadataStore",
+            "ArtifactStore",
+            "ArtifactExportStore",
+            "KnowledgeStore",
+            "VectorIndex",
+            "KeywordIndex",
+            // #271. Unlike the three above it needs no pgvector, so it runs on PGlite in the default local suite.
+            "GraphStore",
+            "UsageRollupStore",
+            "UsageLimitStore",
+            "EvaluationStore",
+        ],
+        notImplemented: POSTGRES_PENDING,
+        notApplicable: [
+            {
+                port: "RateLimitStore",
+                reason: "A rate limiter is a counter on the hot path of every admission, and its correctness rests on an " +
+                    "atomic increment-with-expiry. A relational adapter would mean a write and a row-lock per admitted " +
+                    "run, plus a sweep for expired windows — slower than the thing it protects. Redis has the primitive; " +
+                    "this port has a Redis adapter and an in-memory one for tests, and needs no third (#248).",
+            }, RELATIONAL_CONTENT_EXEMPTION
+        ],
+    },
+    {
+        adapter: "supabase",
+        // `createSupabaseConversationStore` is an alias re-export of the Postgres store
+        // (`adapters/supabase/index.ts`), so Supabase inherits Postgres's coverage rather than being a
+        // second implementation. #104 brings the remaining stores across with RLS applied.
+        //
+        // Derived rather than listed: a Postgres store landing (#93 → #102) must not silently become a
+        // Supabase claim, but it must not become an *unclassified* absence either. Deriving the gap from
+        // what this adapter actually aliases keeps the column honest as Postgres fills in.
+        //
+        // `FileContentStore` joins as of #129 — implemented, not aliased and not exempt. Supabase Storage is a
+        // real second implementation, which is why the alias assertion exempts it by name rather than the
+        // coverage column claiming a gap Supabase does not have.
+        implemented: [...SUPABASE_ALIASED, ...SUPABASE_NATIVE],
+        /**
+         * Derived, and the derivation has to know about `notApplicable` too — #248.
+         *
+         * Filtering only on aliased/native put every never-applicable port into the gap column *as well as* the
+         * not-applicable one, and the guard rightly refused to let a port be claimed both ways. The subtraction is
+         * the point of deriving: a port that will never exist here is not a gap tracked by #104.
+         */
+        notImplemented: REGISTERED_PORTS.filter((p) => !SUPABASE_ALIASED.includes(p.port) &&
+            !SUPABASE_NATIVE.includes(p.port) &&
+            !SUPABASE_NOT_APPLICABLE.includes(p.port)).map((p) => ({ port: p.port, trackedBy: "#104" })),
+        notApplicable: [
+            {
+                port: "RateLimitStore",
+                reason: "A rate limiter is a counter on the hot path of every admission, and its correctness rests on an " +
+                    "atomic increment-with-expiry. A relational adapter would mean a write and a row-lock per admitted " +
+                    "run, plus a sweep for expired windows — slower than the thing it protects. Redis has the primitive; " +
+                    "this port has a Redis adapter and an in-memory one for tests, and needs no third (#248).",
+            },
+        ],
+    },
+];
+/**
+ * The harness sources the isolation guard reads. Listed explicitly rather than globbed so a harness
+ * file that is added but never wired in shows up as a missing harness rather than being skipped.
+ */
+export const HARNESS_MODULES = [
+    "src/testing/conformance/rate-limit.ts",
+    "src/testing/conformance/connections.ts",
+    "src/testing/conformance/conversation-store.ts",
+    "src/testing/conformance/flows.ts",
+    "src/testing/conformance/run-store.ts",
+    "src/testing/conformance/run-event-log.ts",
+    "src/testing/conformance/checkpoint-store.ts",
+    "src/testing/conformance/run-coordinator.ts",
+    "src/testing/conformance/session-state.ts",
+    "src/testing/conformance/records.ts",
+    "src/testing/conformance/hitl.ts",
+    "src/testing/conformance/files.ts",
+    "src/testing/conformance/artifacts.ts",
+    "src/testing/conformance/artifact-exports.ts",
+    "src/testing/conformance/knowledge.ts",
+    "src/testing/conformance/graph.ts",
+    "src/testing/conformance/rollups.ts",
+    "src/testing/conformance/usage-limits.ts",
+    "src/testing/conformance/evaluation.ts",
+];
+export * from "./graph.js";
+export * from "./flows.js";
+//# sourceMappingURL=index.js.map

package/dist/testing/conformance/invariants.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Cross-port invariants — the ones no single-port harness can catch, because each store is
+ * individually correct and the defect lives in the relationship between two of them.
+ *
+ * These are the failures that produced the crash-recovery/event-log desync found in the REQ-005
+ * review: the log and the checkpoint were each self-consistent, and the pair was not.
+ */
+import type { RunEventLog } from "../../core/events.js";
+import type { CheckpointStore, RunStore, UsageStore } from "../../persistence/index.js";
+/**
+ * Split so an adapter can run the invariants it *can* run (#95). Postgres has runs, events and
+ * checkpoints after #95 but no `UsageStore` until #100 — requiring all four would have left the
+ * checkpoint-vs-log-head invariant unverified on the very adapter it matters for. `usage` is
+ * therefore optional, and the usage-dependent case reports why it stood down rather than vanishing.
+ */
+export type InvariantFixture = {
+    readonly runs: RunStore;
+    readonly events: RunEventLog;
+    readonly checkpoints: CheckpointStore;
+    readonly usage?: UsageStore;
+};
+export declare function crossPortInvariants(makeFixture: () => InvariantFixture): void;
+//# sourceMappingURL=invariants.d.ts.map

package/dist/testing/conformance/invariants.js

@@ -0,0 +1,80 @@
+/**
+ * Cross-port invariants — the ones no single-port harness can catch, because each store is
+ * individually correct and the defect lives in the relationship between two of them.
+ *
+ * These are the failures that produced the crash-recovery/event-log desync found in the REQ-005
+ * review: the log and the checkpoint were each self-consistent, and the pair was not.
+ */
+import { describe, expect, it } from "vitest";
+import { asId } from "../../core/ids.js";
+import { emptyCheckpoint } from "../../runtime/checkpoint.js";
+const T1 = asId("conf-tenant-1");
+const CONVO = asId("conf-convo-1");
+const AGENT = asId("conf-agent-1");
+const RUN = asId("conf-run-1");
+const NOW = "2020-01-01T00:00:00.000Z";
+const lifecycle = (sequence) => ({
+    type: "run.checkpointed",
+    runId: RUN,
+    sequence,
+    occurredAt: NOW,
+});
+export function crossPortInvariants(makeFixture) {
+    describe("cross-port invariants", () => {
+        it("a run's events are ordered and gapless from 1 to the head", async () => {
+            const { runs, events } = makeFixture();
+            await runs.create({ tenantId: T1, id: RUN, conversationId: CONVO, agentId: AGENT, agentVersion: 1 });
+            for (const s of [1, 2, 3, 4])
+                await events.append({ tenantId: T1, event: lifecycle(s) });
+            const all = await events.listAfter({ tenantId: T1, runId: RUN, after: 0 });
+            const sequences = all.map((e) => e.sequence);
+            expect(sequences).toEqual([1, 2, 3, 4]);
+            expect(await events.latestSequence({ tenantId: T1, runId: RUN })).toBe(sequences[sequences.length - 1]);
+        });
+        it("a checkpoint never references a sequence beyond the event-log head", async () => {
+            const { runs, events, checkpoints } = makeFixture();
+            await runs.create({ tenantId: T1, id: RUN, conversationId: CONVO, agentId: AGENT, agentVersion: 1 });
+            for (const s of [1, 2, 3])
+                await events.append({ tenantId: T1, event: lifecycle(s) });
+            await checkpoints.save({ tenantId: T1, checkpoint: { ...emptyCheckpoint(RUN, NOW), sequence: 3 } });
+            const head = await events.latestSequence({ tenantId: T1, runId: RUN });
+            const checkpoint = await checkpoints.latest({ tenantId: T1, runId: RUN });
+            // Recovery reads the checkpoint then replays from the log. A checkpoint ahead of the head means
+            // the worker would resume past events that were never durably written.
+            expect(checkpoint?.sequence ?? 0).toBeLessThanOrEqual(head);
+        });
+        it("every usage event resolves to a run that exists", async () => {
+            const { runs, usage } = makeFixture();
+            if (!usage) {
+                // A named, visible stand-down: this adapter has no UsageStore yet (#100 for Postgres). The
+                // assertion below documents the gap so it reads as "not applicable here", never as passing.
+                expect(usage).toBeUndefined();
+                return;
+            }
+            await runs.create({ tenantId: T1, id: RUN, conversationId: CONVO, agentId: AGENT, agentVersion: 1 });
+            const event = {
+                id: "u1",
+                tenantId: T1,
+                runId: RUN,
+                stepId: "step-1",
+                modelId: "claude-opus-5",
+                inputTokens: 10,
+                outputTokens: 5,
+                cachedInputTokens: 0,
+                costMinorUnits: 7,
+                currency: "EUR",
+                occurredAt: NOW,
+            };
+            await usage.append({ tenantId: T1, event });
+            const page = await usage.listByRun({ tenantId: T1, runId: RUN, limit: 10 });
+            for (const recorded of page.items) {
+                expect(await runs.findById({ tenantId: T1, id: recorded.runId })).not.toBeNull();
+            }
+        });
+        it("the event-log head does not advance for a run that was never created", async () => {
+            const { events } = makeFixture();
+            expect(await events.latestSequence({ tenantId: T1, runId: asId("never-created") })).toBe(0);
+        });
+    });
+}
+//# sourceMappingURL=invariants.js.map

package/dist/testing/conformance/knowledge.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `KnowledgeStore` and `VectorIndex` conformance (#135) — AC-6.
+ *
+ * Two harnesses over one fixture, because on pgvector both ports are one table and a suite that opened them
+ * separately would never exercise the case that matters: a search seeing what a write just wrote.
+ *
+ * Both harnesses are gated on the `vector-search` capability. An adapter that cannot hold vectors — Postgres
+ * without pgvector installed, which includes the PGlite the suite runs on by default — declares nothing and
+ * every case registers as a *named* skip rather than vanishing from the report. `gatedIt` exists for exactly
+ * this: an invisible skip is indistinguishable from coverage.
+ *
+ * The search cases assert the **contract**, not recall. pgvector's HNSW index is *approximate*, so
+ * "the nearest chunk comes first" is something the production adapter is permitted to miss on a large corpus —
+ * asserting it here would make the harness fail for a reason that is not a bug. What is asserted is what must
+ * hold exactly at any size: tenant isolation, permission filtering, the limit, score ordering among returned
+ * hits, and that no vector ever comes back. Recall is measured separately against a fixed query set.
+ */
+import { type AdapterDeclaration } from "./capability.js";
+import type { EmbeddingModelRef, KeywordIndex, KnowledgeStore, VectorIndex } from "../../persistence/index.js";
+/** 1536, because that is what the pgvector schema declares and a vector of another length is rejected. */
+export declare const CONFORMANCE_DIMENSIONS = 1536;
+export declare const MODEL: EmbeddingModelRef;
+/**
+ * A deterministic vector pointing mostly along one axis.
+ *
+ * Deterministic because a recall figure that moves between runs is a figure nobody can act on, and axis-aligned
+ * because it makes "closer" obvious: a query along axis 3 must rank the chunk built on axis 3 first, with no
+ * dependence on floating-point luck.
+ */
+export declare const axisVector: (axis: number, magnitude?: number) => readonly number[];
+/** Both ports over the same backing store, which is how pgvector provides them. */
+export type KnowledgeFixture = {
+    readonly store: KnowledgeStore;
+    readonly index: VectorIndex;
+    /** Present once #136's keyword index exists; the harness for it is gated on the same capability. */
+    readonly keyword?: KeywordIndex;
+};
+export declare function knowledgeStoreConformance(make: () => KnowledgeFixture | Promise<KnowledgeFixture>, declaration?: AdapterDeclaration): void;
+export declare function vectorIndexConformance(make: () => KnowledgeFixture | Promise<KnowledgeFixture>, declaration?: AdapterDeclaration): void;
+export declare function keywordIndexConformance(make: () => KnowledgeFixture | Promise<KnowledgeFixture>, declaration?: AdapterDeclaration): void;
+//# sourceMappingURL=knowledge.d.ts.map