@adhd/agent-store-prompts 2.1.0

package/src/store/component-store.js

@@ -0,0 +1,305 @@
+import { and, desc, eq, max } from 'drizzle-orm';
+import { componentsTable, componentVersionsTable, promptTypesTable, } from '../db/schema.js';
+// ──────────────────────────────────────────────
+// Error codes
+// ──────────────────────────────────────────────
+export class ComponentError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ComponentError';
+    }
+}
+// ──────────────────────────────────────────────
+// ComponentStore
+//
+// Thin Drizzle wrapper for the head/version split (Decision 5):
+//   registry_components          — identity (slug PK, type, is_shared)
+//   registry_component_versions  — history  (version_id PK, slug FK, version, content)
+//   registry_prompt_types        — type lookup
+//
+// Public method names + semantics are preserved from the pre-split store: create()
+// returns version 1, read() returns the latest version, version() appends a new
+// version row. The PromptComponent shape gains `versionId` (the stable surrogate a
+// junction version_pin stores).
+//
+// Mirrors the store-class pattern in entrypoint/agent-mcp's AgentStore (agent-cache-store pattern)
+// [ref:store-class] (contexts/_shared.md)
+// ──────────────────────────────────────────────
+export class ComponentStore {
+    db;
+    constructor(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    db) {
+        this.db = db;
+    }
+    // ── Prompt Types ──────────────────────────
+    /** Insert a prompt type. No-op if the slug already exists. */
+    upsertType(input) {
+        this.db
+            .insert(promptTypesTable)
+            .values({
+            slug: input.slug,
+            description: input.description,
+            isSystem: input.isSystem,
+        })
+            .onConflictDoNothing()
+            .run();
+        return input;
+    }
+    /** Read a prompt type by slug. Throws COMPONENT_TYPE_NOT_FOUND if absent. */
+    readType(slug) {
+        const row = this.db
+            .select()
+            .from(promptTypesTable)
+            .where(eq(promptTypesTable.slug, slug))
+            .get();
+        if (!row) {
+            throw new ComponentError('COMPONENT_TYPE_NOT_FOUND', `Prompt type '${slug}' not found`);
+        }
+        return {
+            slug: row.slug,
+            description: row.description,
+            isSystem: Boolean(row.isSystem),
+        };
+    }
+    // ── Prompt Components ─────────────────────
+    /**
+     * Create a new component: insert the head identity row plus its version-1
+     * history row, in ONE transaction (Decision 5).
+     *
+     * [inv:version-retained]: each later call to version() appends a NEW version
+     * row at version+1; it never overwrites a prior version.
+     */
+    create(input) {
+        const now = new Date().toISOString();
+        const isShared = input.isShared ?? false;
+        // Head + first version are written atomically: a version row must never
+        // exist without its head, and a head must always have at least v1.
+        const versionId = this.db.transaction((tx) => {
+            tx.insert(componentsTable)
+                .values({
+                slug: input.slug,
+                type: input.type,
+                isShared,
+                createdAt: now,
+            })
+                .run();
+            const inserted = tx
+                .insert(componentVersionsTable)
+                .values({
+                slug: input.slug,
+                version: 1,
+                content: input.content,
+                createdAt: now,
+                updatedAt: now,
+            })
+                .returning({ versionId: componentVersionsTable.versionId })
+                .get();
+            if (!inserted) {
+                throw new Error(`insert failed: component '${input.slug}' version 1`);
+            }
+            return inserted.versionId;
+        });
+        return {
+            slug: input.slug,
+            type: input.type,
+            version: 1,
+            versionId,
+            content: input.content,
+            isShared,
+            createdAt: now,
+            updatedAt: now,
+        };
+    }
+    /**
+     * Read the latest version of a component by slug (head joined to its highest
+     * version row).
+     * Throws COMPONENT_NOT_FOUND if no head row exists for the slug.
+     */
+    read(slug) {
+        const head = this.db
+            .select()
+            .from(componentsTable)
+            .where(eq(componentsTable.slug, slug))
+            .get();
+        if (!head) {
+            throw new ComponentError('COMPONENT_NOT_FOUND', `Component '${slug}' not found`);
+        }
+        const latest = this.db
+            .select()
+            .from(componentVersionsTable)
+            .where(eq(componentVersionsTable.slug, slug))
+            .orderBy(desc(componentVersionsTable.version))
+            .limit(1)
+            .get();
+        if (!latest) {
+            // Head with no version is an integrity violation (create() writes both
+            // atomically) — surface it rather than returning a malformed component.
+            throw new ComponentError('COMPONENT_NOT_FOUND', `Component '${slug}' has a head row but no versions`);
+        }
+        return this._join(head, latest);
+    }
+    /**
+     * Read a specific version of a component.
+     * Throws COMPONENT_VERSION_NOT_FOUND if that exact (slug, version) row is absent,
+     * or COMPONENT_NOT_FOUND if the head identity row is absent.
+     */
+    readVersion(slug, version) {
+        const head = this.db
+            .select()
+            .from(componentsTable)
+            .where(eq(componentsTable.slug, slug))
+            .get();
+        if (!head) {
+            throw new ComponentError('COMPONENT_NOT_FOUND', `Component '${slug}' not found`);
+        }
+        const row = this.db
+            .select()
+            .from(componentVersionsTable)
+            .where(and(eq(componentVersionsTable.slug, slug), eq(componentVersionsTable.version, version)))
+            .get();
+        if (!row) {
+            throw new ComponentError('COMPONENT_VERSION_NOT_FOUND', `Component '${slug}' version ${version} not found`);
+        }
+        return this._join(head, row);
+    }
+    /**
+     * Resolve a `(slug, version)` pair to its stable registry_component_versions
+     * .version_id surrogate — the value a junction `version_pin` stores when an
+     * exact version is pinned (Decision 5).
+     *
+     * Throws COMPONENT_VERSION_NOT_FOUND if that exact version row is absent.
+     */
+    resolveVersionId(slug, version) {
+        const row = this.db
+            .select({ versionId: componentVersionsTable.versionId })
+            .from(componentVersionsTable)
+            .where(and(eq(componentVersionsTable.slug, slug), eq(componentVersionsTable.version, version)))
+            .get();
+        if (!row) {
+            throw new ComponentError('COMPONENT_VERSION_NOT_FOUND', `Component '${slug}' version ${version} not found`);
+        }
+        return row.versionId;
+    }
+    /**
+     * Bump a component to a new version with updated content.
+     * Appends a NEW version row at max(existing version) + 1 for the slug — the head
+     * identity row is unchanged and old version rows are NEVER deleted.
+     * [inv:version-retained]
+     */
+    version(slug, newContent) {
+        const head = this.db
+            .select()
+            .from(componentsTable)
+            .where(eq(componentsTable.slug, slug))
+            .get();
+        if (!head) {
+            throw new ComponentError('COMPONENT_NOT_FOUND', `Component '${slug}' not found`);
+        }
+        // Highest existing version for the slug → next is +1.
+        const maxRow = this.db
+            .select({
+            maxVersion: max(componentVersionsTable.version).as('max_version'),
+        })
+            .from(componentVersionsTable)
+            .where(eq(componentVersionsTable.slug, slug))
+            .get();
+        const nextVersion = (maxRow?.maxVersion ?? 0) + 1;
+        const now = new Date().toISOString();
+        const inserted = this.db
+            .insert(componentVersionsTable)
+            .values({
+            slug,
+            version: nextVersion,
+            content: newContent,
+            createdAt: now,
+            updatedAt: now,
+        })
+            .returning({ versionId: componentVersionsTable.versionId })
+            .get();
+        if (!inserted) {
+            throw new Error(`insert failed: component '${slug}' version ${nextVersion}`);
+        }
+        const versionId = inserted.versionId;
+        return {
+            slug,
+            type: head.type,
+            version: nextVersion,
+            versionId,
+            content: newContent,
+            isShared: Boolean(head.isShared),
+            createdAt: head.createdAt,
+            updatedAt: now,
+        };
+    }
+    /**
+     * List the latest version of each component, optionally filtered by type
+     * and/or shared flag. Joins each head to its highest version row.
+     */
+    list(filter = {}) {
+        // Subquery: for each slug, find the max version.
+        const maxVersions = this.db
+            .select({
+            slug: componentVersionsTable.slug,
+            maxVersion: max(componentVersionsTable.version).as('max_version'),
+        })
+            .from(componentVersionsTable)
+            .groupBy(componentVersionsTable.slug)
+            .as('max_versions');
+        // Join head identity → its latest version row.
+        let query = this.db
+            .select({
+            slug: componentsTable.slug,
+            type: componentsTable.type,
+            isShared: componentsTable.isShared,
+            headCreatedAt: componentsTable.createdAt,
+            versionId: componentVersionsTable.versionId,
+            version: componentVersionsTable.version,
+            content: componentVersionsTable.content,
+            versionUpdatedAt: componentVersionsTable.updatedAt,
+        })
+            .from(componentsTable)
+            .innerJoin(componentVersionsTable, eq(componentsTable.slug, componentVersionsTable.slug))
+            .innerJoin(maxVersions, and(eq(componentVersionsTable.slug, maxVersions.slug), eq(componentVersionsTable.version, maxVersions.maxVersion)));
+        // Apply filters (Drizzle's .where() can only be called once, so accumulate conditions)
+        const conditions = [];
+        if (filter.type !== undefined) {
+            conditions.push(eq(componentsTable.type, filter.type));
+        }
+        if (filter.shared !== undefined) {
+            conditions.push(eq(componentsTable.isShared, filter.shared));
+        }
+        if (conditions.length > 0) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            query = query.where(and(...conditions));
+        }
+        const rows = query.all();
+        return rows.map((r) => ({
+            slug: r.slug,
+            type: r.type,
+            version: r.version,
+            versionId: r.versionId,
+            content: r.content,
+            isShared: Boolean(r.isShared),
+            createdAt: r.headCreatedAt,
+            updatedAt: r.versionUpdatedAt,
+        }));
+    }
+    // ── Private helpers ───────────────────────
+    /** Join a head identity row to one version row into a PromptComponent. */
+    _join(head, ver) {
+        return {
+            slug: head.slug,
+            type: head.type,
+            version: ver.version,
+            versionId: ver.versionId,
+            content: ver.content,
+            isShared: Boolean(head.isShared),
+            createdAt: head.createdAt,
+            updatedAt: ver.updatedAt,
+        };
+    }
+}
+//# sourceMappingURL=component-store.js.map

package/src/store/component-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-store.js","sourceRoot":"","sources":["../../../../../../packages/agent/agent-store-prompts/src/store/component-store.ts"],"names":[],"mappings":"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"}

package/src/store/composed-prompt-store.d.ts

@@ -0,0 +1,72 @@
+import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
+/**
+ * Compute a deterministic, order-independent SHA-256 hash for a context map.
+ *
+ * Sorted-key JSON canonicalization → SHA-256 hex.
+ * `{ b: "2", a: "1" }` and `{ a: "1", b: "2" }` both hash to the same value.
+ *
+ * This is the canonical implementation reused by @adhd/agent-engine-compiler — import
+ * it from `@adhd/agent-registry` rather than reimplementing.
+ *
+ * @param context - Runtime context key/value map.
+ * @returns 64-character lowercase hex SHA-256 string.
+ */
+export declare function contextHash(context: Record<string, string>): string;
+export declare class ComposedPromptError extends Error {
+    readonly code: 'NOT_FOUND';
+    constructor(code: 'NOT_FOUND', message: string);
+}
+/** A fully-hydrated composed_prompts row with parsed component versions. */
+export interface ComposedPrompt {
+    id: number;
+    agentSlug: string;
+    contextHash: string;
+    content: string;
+    /** Parsed audit map: `{ [componentSlug]: version }`. */
+    componentVersions: Record<string, number>;
+    createdAt: string;
+}
+/** Input required to write a new composed prompt cache entry. */
+export interface ComposedPromptWriteInput {
+    agentSlug: string;
+    contextHash: string;
+    content: string;
+    /** Audit map: `{ [componentSlug]: version }` — which version was used for each component. */
+    componentVersions: Record<string, number>;
+}
+export declare class ComposedPromptStore {
+    private readonly db;
+    constructor(db: BetterSQLite3Database<any>);
+    /**
+     * Write a new composed prompt cache entry.
+     *
+     * The caller is responsible for computing the `contextHash` using the
+     * exported `contextHash()` helper. Inserting a duplicate (agent_slug,
+     * context_hash) is allowed — the cache layer may accumulate redundant rows;
+     * `lookup` will return the most recently written one.
+     *
+     * @returns The inserted row with its generated `id`.
+     */
+    write(input: ComposedPromptWriteInput): ComposedPrompt;
+    /**
+     * Look up a composed prompt by (agent_slug, context_hash).
+     *
+     * Returns the most recently written row for this cache key, or null if no
+     * entry exists. O(1) via the `registry_composed_prompts_agent_hash_idx` index.
+     *
+     * @param agentSlug   - The agent whose cached prompt to retrieve.
+     * @param hash        - The context hash produced by `contextHash()`.
+     * @returns The composed prompt row, or null on a cache miss.
+     */
+    lookup(agentSlug: string, hash: string): ComposedPrompt | null;
+    /**
+     * Read a single composed prompt row by its PK id.
+     *
+     * @param id - The row id returned by `write()`.
+     * @returns The composed prompt row.
+     * @throws ComposedPromptError('NOT_FOUND') if no row with that id exists.
+     */
+    read(id: number): ComposedPrompt;
+    private _rowToComposedPrompt;
+}
+//# sourceMappingURL=composed-prompt-store.d.ts.map

package/src/store/composed-prompt-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composed-prompt-store.d.ts","sourceRoot":"","sources":["../../../../../../packages/agent/agent-store-prompts/src/store/composed-prompt-store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAqBxE;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CASnE;AAMD,qBAAa,mBAAoB,SAAQ,KAAK;aAChB,IAAI,EAAE,WAAW;gBAAjB,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM;CAI/D;AAMD,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,iEAAiE;AACjE,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,6FAA6F;IAC7F,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAeD,qBAAa,mBAAmB;IAG5B,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,qBAAqB,CAAC,GAAG,CAAC;IAGjD;;;;;;;;;OASG;IACH,KAAK,CAAC,KAAK,EAAE,wBAAwB,GAAG,cAAc;IAmBtD;;;;;;;;;OASG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAkB9D;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc;IAmBhC,OAAO,CAAC,oBAAoB;CAoB7B"}

package/src/store/composed-prompt-store.js

@@ -0,0 +1,147 @@
+import { createHash } from 'node:crypto';
+import { and, eq } from 'drizzle-orm';
+import { composedPromptsTable } from '../db/schema.js';
+// ──────────────────────────────────────────────
+// context_hash helper
+//
+// Deterministic + stable: sorts the keys of the context map, JSON-serialises
+// the result, then SHA-256s it. The same input map in any key order always
+// produces an identical hash — the precondition for the composed_prompts cache
+// (Decision 2, decisions.md: the total-order assembly rule makes (agent, context)
+// → byte-identical output; the hash encodes the cache key for that output).
+//
+// This function is EXPORTED from the package barrel so @adhd/agent-engine-compiler can
+// reuse the exact same algorithm (it must match — a different hash in the
+// compiler and the registry would produce permanent cache misses).
+//
+// @param context - An arbitrary key/value string map (runtime context).
+// @returns A hex SHA-256 string; same map with any key ordering → same string.
+// ──────────────────────────────────────────────
+/**
+ * Compute a deterministic, order-independent SHA-256 hash for a context map.
+ *
+ * Sorted-key JSON canonicalization → SHA-256 hex.
+ * `{ b: "2", a: "1" }` and `{ a: "1", b: "2" }` both hash to the same value.
+ *
+ * This is the canonical implementation reused by @adhd/agent-engine-compiler — import
+ * it from `@adhd/agent-registry` rather than reimplementing.
+ *
+ * @param context - Runtime context key/value map.
+ * @returns 64-character lowercase hex SHA-256 string.
+ */
+export function contextHash(context) {
+    // Sort keys to guarantee identical canonical form regardless of insertion order.
+    const sorted = Object.fromEntries(Object.keys(context)
+        .sort()
+        .map((k) => [k, context[k]]));
+    const canonical = JSON.stringify(sorted);
+    return createHash('sha256').update(canonical, 'utf8').digest('hex');
+}
+// ──────────────────────────────────────────────
+// Error codes
+// ──────────────────────────────────────────────
+export class ComposedPromptError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ComposedPromptError';
+    }
+}
+// ──────────────────────────────────────────────
+// ComposedPromptStore
+//
+// Thin Drizzle wrapper for registry_composed_prompts.
+// Three methods:
+//   write(...)           — insert a new cache entry
+//   lookup(slug, hash)   — O(1) cache lookup by (agent_slug, context_hash)
+//   read(id)             — read a single row by PK id
+//
+// [ref:store-class] (contexts/_shared.md)
+// [def:composed-prompt] (contexts/_shared.md)
+// ──────────────────────────────────────────────
+export class ComposedPromptStore {
+    db;
+    constructor(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    db) {
+        this.db = db;
+    }
+    /**
+     * Write a new composed prompt cache entry.
+     *
+     * The caller is responsible for computing the `contextHash` using the
+     * exported `contextHash()` helper. Inserting a duplicate (agent_slug,
+     * context_hash) is allowed — the cache layer may accumulate redundant rows;
+     * `lookup` will return the most recently written one.
+     *
+     * @returns The inserted row with its generated `id`.
+     */
+    write(input) {
+        const now = new Date().toISOString();
+        const componentVersionsJson = JSON.stringify(input.componentVersions);
+        const result = this.db
+            .insert(composedPromptsTable)
+            .values({
+            agentSlug: input.agentSlug,
+            contextHash: input.contextHash,
+            content: input.content,
+            componentVersions: componentVersionsJson,
+            createdAt: now,
+        })
+            .returning()
+            .get();
+        return this._rowToComposedPrompt(result);
+    }
+    /**
+     * Look up a composed prompt by (agent_slug, context_hash).
+     *
+     * Returns the most recently written row for this cache key, or null if no
+     * entry exists. O(1) via the `registry_composed_prompts_agent_hash_idx` index.
+     *
+     * @param agentSlug   - The agent whose cached prompt to retrieve.
+     * @param hash        - The context hash produced by `contextHash()`.
+     * @returns The composed prompt row, or null on a cache miss.
+     */
+    lookup(agentSlug, hash) {
+        // Order by id DESC to get the most recently written row first.
+        const row = this.db
+            .select()
+            .from(composedPromptsTable)
+            .where(and(eq(composedPromptsTable.agentSlug, agentSlug), eq(composedPromptsTable.contextHash, hash)))
+            .orderBy(composedPromptsTable.id)
+            .all()
+            .at(-1); // last (highest id) = most recently written
+        return row ? this._rowToComposedPrompt(row) : null;
+    }
+    /**
+     * Read a single composed prompt row by its PK id.
+     *
+     * @param id - The row id returned by `write()`.
+     * @returns The composed prompt row.
+     * @throws ComposedPromptError('NOT_FOUND') if no row with that id exists.
+     */
+    read(id) {
+        const row = this.db
+            .select()
+            .from(composedPromptsTable)
+            .where(eq(composedPromptsTable.id, id))
+            .get();
+        if (!row) {
+            throw new ComposedPromptError('NOT_FOUND', `Composed prompt id=${id} not found`);
+        }
+        return this._rowToComposedPrompt(row);
+    }
+    // ── Private helpers ───────────────────────
+    _rowToComposedPrompt(row) {
+        return {
+            id: row.id,
+            agentSlug: row.agentSlug,
+            contextHash: row.contextHash,
+            content: row.content,
+            componentVersions: JSON.parse(row.componentVersions),
+            createdAt: row.createdAt,
+        };
+    }
+}
+//# sourceMappingURL=composed-prompt-store.js.map

package/src/store/composed-prompt-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composed-prompt-store.js","sourceRoot":"","sources":["../../../../../../packages/agent/agent-store-prompts/src/store/composed-prompt-store.ts"],"names":[],"mappings":"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"}

package/src/store/composition-store.d.ts

@@ -0,0 +1,117 @@
+import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
+import type { PromptComponent } from './component-store.js';
+export declare class CompositionError extends Error {
+    readonly code: 'AGENT_NOT_FOUND' | 'COMPONENT_VERSION_NOT_FOUND' | 'REQUIRED_COMPONENT_EXCLUDED';
+    constructor(code: 'AGENT_NOT_FOUND' | 'COMPONENT_VERSION_NOT_FOUND' | 'REQUIRED_COMPONENT_EXCLUDED', message: string);
+}
+/**
+ * A runtime context object — arbitrary key/value string pairs.
+ * The context-condition evaluator checks that every key in a predicate
+ * equals the corresponding value in the context (Decision 2, decisions.md).
+ */
+export type CompositionContext = Record<string, string>;
+/** One row from registry_agent_components with its resolved component payload. */
+export interface ResolvedComponent {
+    /** The junction row's component slug. */
+    componentSlug: string;
+    /** Assembly ordering position from the junction row. */
+    position: number;
+    /** The actual version resolved (either pinned or latest-at-resolve-time). */
+    resolvedVersion: number;
+    /** The full component row at the resolved version. */
+    component: PromptComponent;
+}
+/**
+ * Evaluate a context condition predicate against a runtime context.
+ *
+ * @param condition - JSON text predicate, or null for "always include".
+ * @param ctx       - The runtime context key/value map.
+ * @returns true if the component should be included for this context.
+ */
+export declare function evaluateCondition(condition: string | null, ctx: CompositionContext): boolean;
+export declare class CompositionStore {
+    private readonly db;
+    constructor(db: BetterSQLite3Database<any>);
+    /**
+     * Attach a component to an agent at a given position.
+     *
+     * Inserts one row into registry_agent_components. No conflict handling —
+     * callers must ensure the (agent_slug, component_slug, position) triple
+     * is unique or use separate positions for multiple rows at the same position.
+     *
+     * Pinning ergonomics (Decision 5): the stored `version_pin` is a
+     * registry_component_versions.version_id (an ENFORCED nullable FK). Callers may
+     * pin either way:
+     *   - `versionPin`     — a version_id directly (already resolved).
+     *   - `pinVersion`     — a human `version` number; this store resolves it to the
+     *                        matching version_id for `componentSlug` via
+     *                        {@link resolvePinVersionId}.
+     * Supplying both, or a `pinVersion` for a (slug, version) that does not exist,
+     * throws. Omitting both leaves the pin null = resolve latest at resolve-time.
+     */
+    attach(input: {
+        agentSlug: string;
+        componentSlug: string;
+        position: number;
+        /** A registry_component_versions.version_id to pin to (already resolved). */
+        versionPin?: number | null;
+        /** A human version number to pin to; resolved to a version_id for componentSlug. */
+        pinVersion?: number | null;
+        contextCondition?: string | null;
+        isRequired?: boolean;
+    }): void;
+    /**
+     * Resolve a `(slug, version)` pair to its registry_component_versions.version_id
+     * — the value stored as a junction `version_pin` when pinning an exact version.
+     *
+     * Throws COMPONENT_VERSION_NOT_FOUND if that exact version row is absent.
+     */
+    resolvePinVersionId(componentSlug: string, version: number): number;
+    /**
+     * Normalize the two pinning inputs into a single nullable version_id.
+     * Rejects supplying both forms at once.
+     */
+    private _resolvePinInput;
+    /**
+     * Resolve an agent's composition for a given runtime context.
+     *
+     * Steps (per composition-junction context + decisions.md):
+     *  1. Read all junction rows for the agent ordered by position ASC.
+     *  2. For each row, resolve the component version:
+     *       - version_pin IS NULL  → latest version of that component slug.
+     *       - version_pin IS INT   → exactly that version row.
+     *  3. Evaluate context_condition with the shared predicate evaluator:
+     *       - null condition → always included.
+     *       - non-null JSON  → included iff every predicate key matches ctx.
+     *     Exclude non-matching rows.
+     *  4. If a row has is_required = true AND its condition did not match →
+     *     throw CompositionError('REQUIRED_COMPONENT_EXCLUDED').
+     *  5. Return the INCLUDED set ordered by:
+     *       (position ASC, resolvedVersion DESC, componentSlug ASC)
+     *     [Decision 2: total, stable, deterministic order]
+     *
+     * This is the single place ordering + filtering happen — do not duplicate.
+     *
+     * @param agentSlug - The agent whose composition to resolve.
+     * @param ctx       - Runtime context key/value map.
+     * @returns Ordered, filtered list of resolved components. NOT a rendered prompt.
+     *          Markdown assembly is @adhd/agent-engine-compiler's responsibility.
+     */
+    resolveComposition(agentSlug: string, ctx?: CompositionContext): ResolvedComponent[];
+    /**
+     * Resolve a junction row to a specific component version.
+     *
+     * Decision 4 + Decision 5 (decisions.md):
+     *   - pin IS NULL  → max(version) for `slug` at resolution time ("latest").
+     *   - pin IS INT   → the registry_component_versions row whose version_id = pin.
+     *                    That row's `slug` MUST equal the junction's component_slug —
+     *                    a mismatch is an integrity violation and throws.
+     *
+     * Throws COMPONENT_VERSION_NOT_FOUND if the row does not exist (the DB FK makes
+     * this unreachable for a pinned id, but we still guard defensively).
+     */
+    private _resolveComponentVersion;
+    /** Join a head identity row to one version row into a PromptComponent. */
+    private _join;
+}
+//# sourceMappingURL=composition-store.d.ts.map