@elytracms/core 0.0.6

package/dist/persistence/core.js

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+export { createSequentialClock, createSequentialIdFactory, } from '@elytracms/core/studio-core';
+/**
+ * Timestamps every persisted record carries (brief §10). Kept as ISO strings so
+ * fixtures and seeds stay byte-for-byte deterministic across runs.
+ */
+export const recordMetaSchema = z.object({
+    createdAt: z.string().min(1),
+    updatedAt: z.string().min(1),
+});
+/**
+ * Defensive deep clone for records handed back from in-memory repositories, so
+ * callers can never mutate the persisted store by mutating a returned value.
+ * Mirrors the no-aliasing invariant documented in `@elytracms/core/studio-core`'s
+ * `InMemoryProjectRepository`. Records are plain JSON-shaped data.
+ */
+export function cloneRecord(value) {
+    return structuredClone(value);
+}
+/**
+ * Which backend a persistence adapter is talking to, and whether it's reachable.
+ * Lets the Studio surface degraded/offline states without leaking provider types.
+ */
+export const backendKindSchema = z.enum(['in-memory', 'convex']);
+/**
+ * A generic structured issue carried by a {@link PersistenceValidationError}.
+ * Domain issues (graph/cms/binding) are mapped onto this shape so a single error
+ * type can carry any validation failure (brief §4.11).
+ */
+export const persistenceIssueSchema = z.object({
+    code: z.string(),
+    message: z.string(),
+    path: z.array(z.union([z.string(), z.number()])).optional(),
+    /** Originating domain, e.g. 'graph' | 'cms' | 'binding' | 'settings'. */
+    domain: z.string().optional(),
+});
+// --- Error taxonomy (brief §4.10, §7.7) -----------------------------------
+//
+// Provider-neutral, mirrors the project-repository taxonomy in @elytracms/studio-core
+// but is domain-general so every record type shares the same five categories.
+export const persistenceErrorCodeSchema = z.enum([
+    'validation',
+    'not-found',
+    'conflict',
+    'backend-unavailable',
+    'unknown',
+]);
+export class PersistenceError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+/** No record of `kind` exists for the given key. */
+export class RecordNotFoundError extends PersistenceError {
+    kind;
+    key;
+    code = 'not-found';
+    constructor(kind, key) {
+        super(`No ${kind} found for “${key}”.`);
+        this.kind = kind;
+        this.key = key;
+    }
+}
+/** A record would collide with an existing one (unique key/identity). */
+export class RecordConflictError extends PersistenceError {
+    kind;
+    key;
+    code = 'conflict';
+    constructor(kind, key, message) {
+        super(message ?? `A ${kind} with key “${key}” already exists.`);
+        this.kind = kind;
+        this.key = key;
+    }
+}
+/** A write failed structured validation; carries the issues. */
+export class PersistenceValidationError extends PersistenceError {
+    issues;
+    code = 'validation';
+    constructor(message, issues) {
+        super(message);
+        this.issues = issues;
+    }
+}
+/** The backing store is unreachable or returned a transport-level failure. */
+export class BackendUnavailableError extends PersistenceError {
+    code = 'backend-unavailable';
+    constructor(message = 'The persistence backend is unavailable.', options) {
+        super(message, options);
+    }
+}
+/** Any failure that does not map onto a more specific category. */
+export class UnknownPersistenceError extends PersistenceError {
+    code = 'unknown';
+    constructor(message = 'An unknown persistence error occurred.', options) {
+        super(message, options);
+    }
+}
+export function isPersistenceError(value) {
+    return value instanceof PersistenceError;
+}
+/** Normalize any thrown value onto the persistence error taxonomy. */
+export function asPersistenceError(value) {
+    if (isPersistenceError(value))
+        return value;
+    if (value instanceof Error)
+        return new UnknownPersistenceError(value.message, { cause: value });
+    return new UnknownPersistenceError(String(value));
+}
+//# sourceMappingURL=core.js.map

package/dist/persistence/core.js.map

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

package/dist/persistence/graph.d.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import type { ProjectGraph } from '@elytracms/core/project-graph';
+import { type Clock, type IdFactory } from './core';
+/**
+ * An immutable record of one saved graph state (brief §7.1, §10). Each save
+ * appends a revision; the highest revision is the latest. The graph is stored
+ * serialized so reload is provably lossless (serialize → parse round-trip).
+ */
+export declare const graphRevisionRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    projectId: z.ZodString;
+    revision: z.ZodNumber;
+    serializedGraph: z.ZodString;
+    schemaVersion: z.ZodNumber;
+    createdAt: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type GraphRevisionRecord = z.infer<typeof graphRevisionRecordSchema>;
+/** A revision paired with its parsed graph. */
+export interface LoadedGraph {
+    graph: ProjectGraph;
+    revision: GraphRevisionRecord;
+}
+export interface SaveGraphOptions {
+    label?: string;
+    message?: string;
+}
+/**
+ * Persists project graphs and their revision history (brief §7.1, §10).
+ * Provider-neutral: an in-memory and a Convex implementation both satisfy it.
+ */
+export interface GraphRepository {
+    /** Append a new revision for the project's graph and return it. */
+    saveGraph(projectId: string, graph: ProjectGraph, options?: SaveGraphOptions): Promise<GraphRevisionRecord>;
+    /** Load the latest graph + revision. Throws `RecordNotFoundError` if none. */
+    getLatest(projectId: string): Promise<LoadedGraph>;
+    /** Load a specific revision. Throws `RecordNotFoundError` if absent. */
+    getRevision(projectId: string, revision: number): Promise<LoadedGraph>;
+    /** All revisions for a project, newest first. */
+    listRevisions(projectId: string): Promise<GraphRevisionRecord[]>;
+    /** Whether any graph revision exists for the project. */
+    hasGraph(projectId: string): Promise<boolean>;
+}
+export interface InMemoryGraphRepositoryOptions {
+    clock?: Clock;
+    idFactory?: IdFactory;
+    seed?: readonly GraphRevisionRecord[];
+}
+export declare class InMemoryGraphRepository implements GraphRepository {
+    /** projectId → revisions in ascending revision order. */
+    private readonly byProject;
+    private readonly clock;
+    private readonly nextId;
+    constructor(options?: InMemoryGraphRepositoryOptions);
+    saveGraph(projectId: string, graph: ProjectGraph, options?: SaveGraphOptions): Promise<GraphRevisionRecord>;
+    getLatest(projectId: string): Promise<LoadedGraph>;
+    getRevision(projectId: string, revision: number): Promise<LoadedGraph>;
+    listRevisions(projectId: string): Promise<GraphRevisionRecord[]>;
+    hasGraph(projectId: string): Promise<boolean>;
+}

package/dist/persistence/graph.js

@@ -0,0 +1,98 @@
+import { z } from 'zod';
+import { PROJECT_GRAPH_SCHEMA_VERSION, parseProjectGraph, serializeProjectGraph, } from '@elytracms/core/project-graph';
+import { PersistenceValidationError, RecordNotFoundError, cloneRecord, createSequentialClock, createSequentialIdFactory, } from './core';
+/**
+ * An immutable record of one saved graph state (brief §7.1, §10). Each save
+ * appends a revision; the highest revision is the latest. The graph is stored
+ * serialized so reload is provably lossless (serialize → parse round-trip).
+ */
+export const graphRevisionRecordSchema = z.object({
+    id: z.string().min(1),
+    projectId: z.string().min(1),
+    /** 1-based, monotonically increasing per project. */
+    revision: z.number().int().positive(),
+    /** Serialized `ProjectGraph` JSON. */
+    serializedGraph: z.string().min(1),
+    schemaVersion: z.number().int(),
+    createdAt: z.string().min(1),
+    /** Optional short label, e.g. "Initial import". */
+    label: z.string().optional(),
+    /** Optional longer message describing the change. */
+    message: z.string().optional(),
+});
+function loaded(record) {
+    const parsed = parseProjectGraph(record.serializedGraph);
+    if (!parsed.ok) {
+        // A stored revision should always reparse; if not, the store is corrupt.
+        throw new PersistenceValidationError('Stored graph failed to parse.', [
+            { code: 'corrupt-graph', message: 'Stored graph revision is not parseable.', domain: 'graph' },
+        ]);
+    }
+    return { graph: parsed.graph, revision: cloneRecord(record) };
+}
+export class InMemoryGraphRepository {
+    /** projectId → revisions in ascending revision order. */
+    byProject = new Map();
+    clock;
+    nextId;
+    constructor(options = {}) {
+        this.clock = options.clock ?? createSequentialClock();
+        this.nextId = options.idFactory ?? createSequentialIdFactory('rev');
+        for (const record of options.seed ?? []) {
+            const list = this.byProject.get(record.projectId) ?? [];
+            list.push(graphRevisionRecordSchema.parse(record));
+            list.sort((a, b) => a.revision - b.revision);
+            this.byProject.set(record.projectId, list);
+        }
+    }
+    async saveGraph(projectId, graph, options = {}) {
+        let serializedGraph;
+        try {
+            serializedGraph = serializeProjectGraph(graph);
+        }
+        catch (error) {
+            throw new PersistenceValidationError('Graph is not well-formed and cannot be persisted.', [
+                {
+                    code: 'invalid-graph',
+                    message: error instanceof Error ? error.message : String(error),
+                    domain: 'graph',
+                },
+            ]);
+        }
+        const list = this.byProject.get(projectId) ?? [];
+        const revision = (list.at(-1)?.revision ?? 0) + 1;
+        const record = {
+            id: this.nextId(),
+            projectId,
+            revision,
+            serializedGraph,
+            schemaVersion: graph.schemaVersion ?? PROJECT_GRAPH_SCHEMA_VERSION,
+            createdAt: this.clock(),
+            ...(options.label ? { label: options.label } : {}),
+            ...(options.message ? { message: options.message } : {}),
+        };
+        list.push(record);
+        this.byProject.set(projectId, list);
+        return cloneRecord(record);
+    }
+    async getLatest(projectId) {
+        const list = this.byProject.get(projectId);
+        const latest = list?.at(-1);
+        if (!latest)
+            throw new RecordNotFoundError('graph', projectId);
+        return loaded(latest);
+    }
+    async getRevision(projectId, revision) {
+        const record = this.byProject.get(projectId)?.find((r) => r.revision === revision);
+        if (!record)
+            throw new RecordNotFoundError('graph-revision', `${projectId}#${revision}`);
+        return loaded(record);
+    }
+    async listRevisions(projectId) {
+        return [...(this.byProject.get(projectId) ?? [])].reverse().map(cloneRecord);
+    }
+    async hasGraph(projectId) {
+        return (this.byProject.get(projectId)?.length ?? 0) > 0;
+    }
+}
+//# sourceMappingURL=graph.js.map

package/dist/persistence/graph.js.map

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

package/dist/persistence/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @elytracms/persistence — provider-neutral persistence contracts + in-memory
+ * implementations (brief §4.10, §10). Core packages depend on these interfaces,
+ * never on Convex directly; a Convex-backed adapter and the in-memory adapter
+ * here both satisfy {@link PersistenceAdapter}.
+ */
+export declare const PACKAGE = "@elytracms/core/persistence";
+export * from './core';
+export * from './graph';
+export * from './cms';
+export * from './assets';
+export * from './publishing';
+export * from './references';
+export * from './members';
+export * from './cli-tokens';
+export * from './reference-extraction';
+export * from './reference-indexing';
+export * from './self-maintaining-adapter';
+export * from './backend-validation';
+export * from './adapter';
+export * from './seed';
+export * from './contract-scenarios';

package/dist/persistence/index.js

@@ -0,0 +1,23 @@
+/**
+ * @elytracms/persistence — provider-neutral persistence contracts + in-memory
+ * implementations (brief §4.10, §10). Core packages depend on these interfaces,
+ * never on Convex directly; a Convex-backed adapter and the in-memory adapter
+ * here both satisfy {@link PersistenceAdapter}.
+ */
+export const PACKAGE = '@elytracms/core/persistence';
+export * from './core';
+export * from './graph';
+export * from './cms';
+export * from './assets';
+export * from './publishing';
+export * from './references';
+export * from './members';
+export * from './cli-tokens';
+export * from './reference-extraction';
+export * from './reference-indexing';
+export * from './self-maintaining-adapter';
+export * from './backend-validation';
+export * from './adapter';
+export * from './seed';
+export * from './contract-scenarios';
+//# sourceMappingURL=index.js.map

package/dist/persistence/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/persistence/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,6BAA6B,CAAA;AAEpD,cAAc,QAAQ,CAAA;AACtB,cAAc,SAAS,CAAA;AACvB,cAAc,OAAO,CAAA;AACrB,cAAc,UAAU,CAAA;AACxB,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA;AAC5B,cAAc,wBAAwB,CAAA;AACtC,cAAc,sBAAsB,CAAA;AACpC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,sBAAsB,CAAA;AACpC,cAAc,WAAW,CAAA;AACzB,cAAc,QAAQ,CAAA;AACtB,cAAc,sBAAsB,CAAA"}

package/dist/persistence/members.d.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import type { Clock } from './core';
+/**
+ * Per-project membership records (EC-150, vision AD-7). The role model is
+ * deliberately minimal for v1 — three roles, project-scoped, no field-level
+ * permissions. Workspace-level grants (who may create projects, default
+ * memberships) land with EC-154; everything here stays project-scoped.
+ *
+ * Roles:
+ * - `viewer`  — read-only: queries succeed, every command is denied.
+ * - `editor`  — edits and publishes content, but cannot administer the project
+ *               (lifecycle, settings, members, CLI tokens).
+ * - `admin`   — everything within the project.
+ *
+ * Enforcement lives at the operations chokepoint
+ * (`@elytracms/core/operations` `createRoleAuthorization`) and server-side in the
+ * Convex functions (`apps/builder/convex/guard.ts`); this module only defines
+ * the storage contract.
+ */
+export declare const projectRoleSchema: z.ZodEnum<{
+    admin: "admin";
+    editor: "editor";
+    viewer: "viewer";
+}>;
+export type ProjectRole = z.infer<typeof projectRoleSchema>;
+/** True when `role` grants at least the capabilities of `required`. */
+export declare function roleAtLeast(role: ProjectRole, required: ProjectRole): boolean;
+export declare const projectMemberRecordSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    userId: z.ZodString;
+    role: z.ZodEnum<{
+        admin: "admin";
+        editor: "editor";
+        viewer: "viewer";
+    }>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type ProjectMemberRecord = z.infer<typeof projectMemberRecordSchema>;
+/**
+ * Membership storage boundary. Mirrors the other repository contracts: the
+ * in-memory implementation below and the Convex-backed implementation in
+ * `apps/builder` both satisfy it.
+ */
+export interface MembersRepository {
+    /** Upsert a membership (add a member or change their role). */
+    setMember(projectId: string, userId: string, role: ProjectRole): Promise<ProjectMemberRecord>;
+    /** Look up one membership; `undefined` when the user is not a member. */
+    findMember(projectId: string, userId: string): Promise<ProjectMemberRecord | undefined>;
+    /** All members of a project, ordered by userId for determinism. */
+    listMembers(projectId: string): Promise<ProjectMemberRecord[]>;
+    /** All memberships of a user across projects, ordered by projectId. */
+    listMembershipsForUser(userId: string): Promise<ProjectMemberRecord[]>;
+    /** Remove a membership. Throws `RecordNotFoundError` when absent. */
+    removeMember(projectId: string, userId: string): Promise<void>;
+}
+export interface InMemoryMembersRepositoryOptions {
+    clock?: Clock;
+    seed?: readonly ProjectMemberRecord[];
+}
+export declare class InMemoryMembersRepository implements MembersRepository {
+    private readonly records;
+    private readonly clock;
+    constructor(options?: InMemoryMembersRepositoryOptions);
+    setMember(projectId: string, userId: string, role: ProjectRole): Promise<ProjectMemberRecord>;
+    findMember(projectId: string, userId: string): Promise<ProjectMemberRecord | undefined>;
+    listMembers(projectId: string): Promise<ProjectMemberRecord[]>;
+    listMembershipsForUser(userId: string): Promise<ProjectMemberRecord[]>;
+    removeMember(projectId: string, userId: string): Promise<void>;
+}

package/dist/persistence/members.js.map

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

package/dist/persistence/publishing.d.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { type Clock } from './core';
+/** Draft vs published — distinct, queryable publishing states (brief §10). */
+export declare const publishingStatusSchema: z.ZodEnum<{
+    draft: "draft";
+    published: "published";
+}>;
+export type PublishingStatus = z.infer<typeof publishingStatusSchema>;
+/**
+ * Publishing state (brief §10). Single-environment (EC-179, vision AD-8): a
+ * deployment IS one environment, so there is exactly ONE publishing-state
+ * record per project. A `published` record pins the graph revision that is
+ * live. Moving a release between environments is a deployment/code-pipeline
+ * concern, not an in-deployment dimension — see `env-is-deployment-boundary`.
+ */
+export declare const publishingStateRecordSchema: z.ZodObject<{
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    projectId: z.ZodString;
+    status: z.ZodEnum<{
+        draft: "draft";
+        published: "published";
+    }>;
+    publishedRevisionId: z.ZodOptional<z.ZodString>;
+    publishedRevision: z.ZodOptional<z.ZodNumber>;
+    publishedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PublishingStateRecord = z.infer<typeof publishingStateRecordSchema>;
+export interface PublishInput {
+    revisionId: string;
+    revision: number;
+}
+/**
+ * Persists and transitions publishing state (brief §10). Transitions are
+ * validated: publishing requires a revision; unpublishing requires a
+ * currently-published deployment.
+ */
+export interface PublishingRepository {
+    getState(projectId: string): Promise<PublishingStateRecord>;
+    findState(projectId: string): Promise<PublishingStateRecord | undefined>;
+    /** Publish a graph revision. */
+    publish(projectId: string, input: PublishInput): Promise<PublishingStateRecord>;
+    /** Revert to draft (must currently be published). */
+    unpublish(projectId: string): Promise<PublishingStateRecord>;
+}
+export interface InMemoryPublishingRepositoryOptions {
+    clock?: Clock;
+    seed?: readonly PublishingStateRecord[];
+}
+export declare class InMemoryPublishingRepository implements PublishingRepository {
+    /** projectId → record (one per deployment). */
+    private readonly byProject;
+    private readonly clock;
+    constructor(options?: InMemoryPublishingRepositoryOptions);
+    getState(projectId: string): Promise<PublishingStateRecord>;
+    findState(projectId: string): Promise<PublishingStateRecord | undefined>;
+    publish(projectId: string, input: PublishInput): Promise<PublishingStateRecord>;
+    unpublish(projectId: string): Promise<PublishingStateRecord>;
+}

package/dist/persistence/publishing.js

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+import { PersistenceValidationError, RecordNotFoundError, cloneRecord, recordMetaSchema, createSequentialClock, } from './core';
+/** Draft vs published — distinct, queryable publishing states (brief §10). */
+export const publishingStatusSchema = z.enum(['draft', 'published']);
+/**
+ * Publishing state (brief §10). Single-environment (EC-179, vision AD-8): a
+ * deployment IS one environment, so there is exactly ONE publishing-state
+ * record per project. A `published` record pins the graph revision that is
+ * live. Moving a release between environments is a deployment/code-pipeline
+ * concern, not an in-deployment dimension — see `env-is-deployment-boundary`.
+ */
+export const publishingStateRecordSchema = recordMetaSchema.extend({
+    projectId: z.string().min(1),
+    status: publishingStatusSchema,
+    /** Graph revision pinned live (when published). */
+    publishedRevisionId: z.string().optional(),
+    publishedRevision: z.number().int().positive().optional(),
+    publishedAt: z.string().optional(),
+});
+export class InMemoryPublishingRepository {
+    /** projectId → record (one per deployment). */
+    byProject = new Map();
+    clock;
+    constructor(options = {}) {
+        this.clock = options.clock ?? createSequentialClock();
+        for (const record of options.seed ?? []) {
+            const parsed = publishingStateRecordSchema.parse(record);
+            this.byProject.set(parsed.projectId, parsed);
+        }
+    }
+    async getState(projectId) {
+        const record = this.byProject.get(projectId);
+        if (!record)
+            throw new RecordNotFoundError('publishing-state', projectId);
+        return cloneRecord(record);
+    }
+    async findState(projectId) {
+        const record = this.byProject.get(projectId);
+        return record ? cloneRecord(record) : undefined;
+    }
+    async publish(projectId, input) {
+        if (!input.revisionId) {
+            throw new PersistenceValidationError('Cannot publish without a graph revision.', [
+                {
+                    code: 'missing-revision',
+                    message: 'A revision id is required to publish.',
+                    domain: 'publishing',
+                },
+            ]);
+        }
+        if (!Number.isInteger(input.revision) || input.revision < 1) {
+            throw new PersistenceValidationError('Cannot publish an invalid revision number.', [
+                {
+                    code: 'invalid-revision',
+                    message: `Revision must be a positive integer (got ${input.revision}).`,
+                    domain: 'publishing',
+                },
+            ]);
+        }
+        const now = this.clock();
+        const previous = this.byProject.get(projectId);
+        const record = {
+            projectId,
+            status: 'published',
+            publishedRevisionId: input.revisionId,
+            publishedRevision: input.revision,
+            publishedAt: now,
+            createdAt: previous?.createdAt ?? now,
+            updatedAt: now,
+        };
+        this.byProject.set(projectId, record);
+        return cloneRecord(record);
+    }
+    async unpublish(projectId) {
+        const existing = this.byProject.get(projectId);
+        if (!existing || existing.status !== 'published') {
+            throw new PersistenceValidationError('Deployment is not currently published.', [
+                {
+                    code: 'invalid-transition',
+                    message: 'Cannot unpublish: nothing is currently published.',
+                    domain: 'publishing',
+                },
+            ]);
+        }
+        const updated = {
+            projectId,
+            status: 'draft',
+            createdAt: existing.createdAt,
+            updatedAt: this.clock(),
+        };
+        this.byProject.set(projectId, updated);
+        return cloneRecord(updated);
+    }
+}
+//# sourceMappingURL=publishing.js.map

package/dist/persistence/publishing.js.map

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

package/dist/persistence/reference-extraction.d.ts

@@ -0,0 +1,44 @@
+import type { CmsDocument } from '@elytracms/core/cms-core';
+import type { ComponentNode, ProjectGraph } from '@elytracms/core/project-graph';
+import type { OutboundReference, ReferenceEntry } from './references';
+/**
+ * Reference extraction (EC-155, vision AD-6 — reshaped by EC-277/AD-15).
+ *
+ * Self-describing content makes extraction a **schema-free, manifest-free walk** over
+ * the stored value: every reference-bearing node carries an explicit `type`
+ * discriminator (`{ type:'reference', … }`, `{ type:'asset', … }`), and composition
+ * nodes self-type via `componentId`. So a single pure function reads the value and
+ * needs neither the collection schema nor the component manifest — which is exactly
+ * what lets the same walk run in the studio, the CLI, or a Convex mutation (AD-6,
+ * "maintained on write, every writer caught by construction").
+ *
+ * The `kind` is derived from *walk context*: a reference/asset node in a normal value
+ * position → `relation-field`/`asset-field`; inside a rich-text mark → `rich-text-link`;
+ * in a rich-text node's attrs → `rich-text-node`; a composition node's `componentId` →
+ * `component-usage`. Bindings are out of scope (v1 is static-only; see EC-278): a
+ * binding has no self-typed value, so it contributes no reference.
+ */
+/** Join `/`-separated path tokens (numbers are array indices). */
+export declare function referencePath(...segments: ReadonlyArray<string | number>): string;
+/**
+ * Extract every outbound reference held by one self-describing CMS document — no
+ * schema, no manifest, no binding context (EC-277). Walks `values/<field>` and
+ * `localized/<locale>/<field>` (just object keys), then descends each value by its
+ * self-typed shape. The returned order is walk order; callers that compare must sort
+ * (the index repository sorts via `compareReferenceEntries`), so this stays
+ * drift-tolerant: a reference in a field the schema no longer declares is still found.
+ */
+export declare function extractReferences(document: CmsDocument): OutboundReference[];
+/**
+ * Extract every outbound reference held by one self-describing layout root (EC-277).
+ * The graph (EC-187) is layouts-only; pages live in the `page` collection's `body`.
+ */
+export declare function extractLayoutReferences(layout: {
+    id: string;
+    root: ComponentNode;
+}): ReferenceEntry[];
+/**
+ * Schema-free, manifest-free graph extraction (EC-277): component usage + self-typed
+ * static props across every layout, in deterministic (id-sorted) order.
+ */
+export declare function extractSelfTypedGraphReferences(graph: ProjectGraph): ReferenceEntry[];