@functional-systems/srcx 0.1.0-dev.1

package/dist/publish.js

@@ -0,0 +1,341 @@
+import { mkdir, rm, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { atomic, canonical, hash, invariant, optionalJson, sleep, } from "./common.js";
+import { corpusMetadata, records, validateBuild } from "./build.js";
+import { branch, tag, one } from "./remote.js";
+export function versionTag(oid) {
+    return `ver-${hash(oid).slice(0, 40)}`;
+}
+export function versionId(oid) {
+    return `version-${oid}`;
+}
+export async function exclusive(directory, work) {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const lock = join(directory, "writer.lock");
+    try {
+        await mkdir(lock, { mode: 0o700 });
+    }
+    catch (e) {
+        if (e.code === "EEXIST") {
+            let owner = "unknown";
+            try {
+                owner = await readFile(join(lock, "owner.json"), "utf8");
+            }
+            catch { }
+            throw new Error(`Collection is locked: ${lock}. Owner: ${owner.trim()}. After a crash, verify no importing process is running before removing this lock directory.`);
+        }
+        throw e;
+    }
+    try {
+        await atomic(join(lock, "owner.json"), {
+            pid: process.pid,
+            startedAt: new Date().toISOString(),
+        });
+        return await work();
+    }
+    finally {
+        await rm(lock, { recursive: true, force: true });
+    }
+}
+export function matchesManifest(doc, b, binding, attemptId) {
+    return (!!doc &&
+        doc.kind === "manifest" &&
+        doc.role === "corpus" &&
+        doc.repoId === binding.repoId &&
+        doc.indexId === binding.indexId &&
+        doc.configHash === b.configHash &&
+        doc.commitOid === b.commitOid &&
+        doc.buildId === b.buildId &&
+        doc.recordsHash === b.recordsHash &&
+        doc.inventoryHash === b.inventoryHash &&
+        (!attemptId || doc.attemptId === attemptId));
+}
+/** Exact immutable inventory/content comparison, not merely a marker/count check. */
+export async function validateCandidate(store, name, b, binding, attemptId) {
+    const root = await one(store, tag(name), "__manifest__");
+    if (!matchesManifest(root, b, binding, attemptId))
+        return false;
+    const expected = new Map(Object.entries(b.recordHashes));
+    for (const d of corpusMetadata(b, binding.repoId, binding.indexId, attemptId))
+        expected.set(d.id, hash(d));
+    for await (const d of store.list(tag(name))) {
+        if (expected.get(d.id) !== hash(d))
+            return false;
+        expected.delete(d.id);
+    }
+    if (expected.size)
+        return false;
+    if (b.counts.chunks) {
+        let query = {
+            queryString: { query: "kind:chunk" },
+        };
+        for await (const d of records(b.directory)) {
+            if (d.kind !== "chunk")
+                continue;
+            // Keep a complete surface token: the standard analyzer may retain dots
+            // (e.g. code.ts), so extracting an alphanumeric substring is not a valid probe.
+            const term = String(d.symbol ?? d.searchText).match(/\S+/u)?.[0];
+            if (!term)
+                continue;
+            query = {
+                bool: [
+                    {
+                        queryString: {
+                            query: "chunk",
+                            defaultField: "kind",
+                            skipSyntax: true,
+                        },
+                        occur: "filter",
+                    },
+                    {
+                        queryString: {
+                            query: d.fileId,
+                            defaultField: "fileId",
+                            skipSyntax: true,
+                        },
+                        occur: "filter",
+                    },
+                    {
+                        queryString: {
+                            query: term,
+                            defaultField: "searchText",
+                            skipSyntax: true,
+                        },
+                        occur: "must",
+                    },
+                ],
+            };
+            break;
+        }
+        const found = await store.query(name, query, 1);
+        if (!found.length ||
+            found.some((h) => h.doc.kind !== "chunk" || b.recordHashes[h.doc.id] !== hash(h.doc)))
+            return false;
+    }
+    return true;
+}
+async function* batches(input) {
+    let batch = [];
+    let bytes = 32;
+    for await (const doc of input) {
+        const size = Buffer.byteLength(canonical(doc)) + 1;
+        invariant(size < 4_900_000, "Document exceeds safe request limit.");
+        if (batch.length >= 500 || bytes + size > 4_900_000) {
+            yield batch;
+            batch = [];
+            bytes = 32;
+        }
+        batch.push(doc);
+        bytes += size;
+    }
+    if (batch.length)
+        yield batch;
+}
+export async function published(store, binding) {
+    const tags = await store.tags();
+    const result = [];
+    // Control reads include accepted writes, while code reads always pin an immutable Tag.
+    for (const t of tags.filter((t) => t.name.startsWith("ver-"))) {
+        const root = await one(store, tag(t.name), "__manifest__");
+        if (!root ||
+            root.repoId !== binding.repoId ||
+            root.indexId !== binding.indexId ||
+            root.configHash !== binding.configHash)
+            continue;
+        const v = await one(store, branch("main"), versionId(String(root.commitOid)), true);
+        if (v?.role === "published" &&
+            v.tagName === t.name &&
+            v.snapshotId === t.snapshotId &&
+            v.buildId === root.buildId &&
+            v.attemptId === root.attemptId &&
+            v.recordsHash === root.recordsHash &&
+            v.inventoryHash === root.inventoryHash)
+            result.push(v);
+    }
+    return result.sort((a, b) => String(a.commitTime).localeCompare(String(b.commitTime)) ||
+        a.commitOid.localeCompare(b.commitOid));
+}
+/** Caller holds the per-collection lock for the complete import. */
+export async function publish(args) {
+    const { store, binding, build: b, state } = args;
+    invariant(b.repoKey === binding.repoKey && b.configHash === binding.configHash, "Build does not belong to this index.");
+    invariant(!b.preset.embedding, "CLI publication currently supports only the embedding=none preset.");
+    await validateBuild(b);
+    const journalPath = join(state, "pending.json");
+    let j = await optionalJson(journalPath);
+    if (j) {
+        invariant(j.buildId === b.buildId &&
+            j.recordsHash === b.recordsHash &&
+            j.inventoryHash === b.inventoryHash, "Another build is pending. Resume the artifact recorded in pending.json before importing a new commit.");
+        invariant(args.resume, "Pending import found; use --resume with the same artifact.");
+    }
+    const existing = (await published(store, binding)).find((v) => v.commitOid === b.commitOid);
+    if (existing) {
+        invariant(await validateCandidate(store, existing.tagName, b, binding, existing.attemptId), "Existing published version differs from this build.");
+        await atomic(join(state, "last-build.json"), {
+            artifact: b.directory,
+            version: existing,
+        });
+        if (j)
+            await rm(journalPath);
+        return existing;
+    }
+    if (!j) {
+        let source = "checkpoint-empty";
+        let baseline;
+        if (args.baseline) {
+            const prev = args.baseline;
+            await validateBuild(prev.build);
+            invariant(prev.build.repoKey === b.repoKey &&
+                prev.build.configHash === b.configHash, "Baseline configuration mismatch.");
+            const current = (await store.branches()).find((x) => x.name === prev.version.writer);
+            invariant(current?.snapshotId === prev.version.snapshotId, "Writer baseline has changed; refusing to fork it.");
+            invariant(await validateCandidate(store, prev.version.tagName, prev.build, binding, prev.version.attemptId), "Baseline Tag validation failed.");
+            source = prev.version.writer;
+            baseline = prev.version;
+        }
+        const attemptId = randomUUID();
+        j = {
+            buildId: b.buildId,
+            recordsHash: b.recordsHash,
+            inventoryHash: b.inventoryHash,
+            artifact: b.directory,
+            attemptId,
+            writer: `work-${attemptId}`,
+            source,
+            baseline,
+            phase: "branch",
+            batches: [],
+        };
+        await atomic(journalPath, j);
+    }
+    const save = () => atomic(journalPath, j);
+    if (j.phase === "branch") {
+        const branches = await store.branches();
+        const found = branches.find((x) => x.name === j.writer);
+        if (found)
+            invariant(found.parent === j.source &&
+                found.snapshotId === (j.baseline?.snapshotId ?? null), "Partially created writer has an unexpected baseline.");
+        else {
+            const source = branches.find((x) => x.name === j.source);
+            invariant(source &&
+                (j.baseline
+                    ? source.snapshotId === j.baseline.snapshotId
+                    : source.snapshotId === null), "Source Branch is no longer the expected baseline.");
+            await store.branch(j.writer, j.source);
+        }
+        j.phase = "writing";
+        await save();
+    }
+    const metadata = corpusMetadata(b, binding.repoId, binding.indexId, j.attemptId);
+    const marker = metadata.at(-1);
+    if (j.phase === "writing") {
+        // Reconcile from the immutable old Tag, never from a half-written writer.
+        const oldIds = new Set();
+        const oldHashes = new Map();
+        if (j.baseline)
+            for await (const d of store.list(tag(j.baseline.tagName))) {
+                oldIds.add(d.id);
+                oldHashes.set(d.id, hash(d));
+            }
+        const newIds = new Set([
+            ...Object.keys(b.recordHashes),
+            ...metadata.map((d) => d.id),
+        ]);
+        const obsolete = [...oldIds].filter((id) => !newIds.has(id));
+        const mutate = async (operation, payload, send) => {
+            const receipt = {
+                operation,
+                hash: hash(payload),
+                outcome: "unknown",
+            };
+            j.batches.push(receipt);
+            await save();
+            await send();
+            receipt.outcome = "accepted";
+            await save();
+        };
+        for (let i = 0; i < obsolete.length; i += 500) {
+            const ids = obsolete.slice(i, i + 500);
+            await mutate("delete", ids, () => store.delete(j.writer, ids));
+        }
+        async function* changed() {
+            for await (const d of records(b.directory))
+                if (oldHashes.get(d.id) !== hash(d))
+                    yield d;
+            for (const d of metadata.slice(0, -1))
+                yield d;
+        }
+        for await (const docs of batches(changed()))
+            await mutate("upsert", docs, () => store.upsert(j.writer, docs));
+        // An explicit same-build replay supersedes unknown earlier receipts only after every write ACKs.
+        await mutate("final-marker", [marker], () => store.upsert(j.writer, [marker]));
+        for (const receipt of j.batches)
+            if (receipt.outcome === "unknown")
+                receipt.outcome = "superseded";
+        j.phase = "waiting";
+        await save();
+    }
+    const deadline = Date.now() + (args.timeoutMs ?? 120_000);
+    const pause = args.pollMs ?? 1000;
+    let rejectedSnapshot;
+    while (j.phase === "waiting") {
+        invariant(Date.now() < deadline, "Index validation timed out; build remains unpublished. Resume this artifact with --resume.");
+        const visible = await one(store, branch(j.writer), "__manifest__", false);
+        if (!matchesManifest(visible, b, binding, j.attemptId)) {
+            await sleep(pause);
+            continue;
+        }
+        if (rejectedSnapshot) {
+            const head = (await store.branches()).find((b) => b.name === j.writer)?.snapshotId;
+            if (!head || head === rejectedSnapshot) {
+                await sleep(pause);
+                continue;
+            }
+        }
+        const candidate = await store.tag(`try-${randomUUID()}`, branch(j.writer));
+        if (!(await validateCandidate(store, candidate.name, b, binding, j.attemptId))) {
+            rejectedSnapshot = candidate.snapshotId;
+            await sleep(pause);
+            continue;
+        }
+        j.candidate = candidate;
+        j.phase = "publishing";
+        await save();
+    }
+    invariant(j.candidate, "Missing validated candidate.");
+    invariant(await validateCandidate(store, j.candidate.name, b, binding, j.attemptId), "Validated candidate is missing or changed.");
+    const name = versionTag(b.commitOid);
+    const found = (await store.tags()).find((t) => t.name === name);
+    const final = found ?? (await store.tag(name, tag(j.candidate.name)));
+    invariant(final.snapshotId === j.candidate.snapshotId, "Published Tag name already points to a different snapshot.");
+    const result = {
+        id: versionId(b.commitOid),
+        kind: "manifest",
+        role: "published",
+        schemaVersion: 1,
+        configHash: b.configHash,
+        repoId: binding.repoId,
+        indexId: binding.indexId,
+        commitOid: b.commitOid,
+        commitTime: b.commitTime,
+        tagName: name,
+        snapshotId: final.snapshotId,
+        writer: j.writer,
+        buildId: b.buildId,
+        recordsHash: b.recordsHash,
+        inventoryHash: b.inventoryHash,
+        attemptId: j.attemptId,
+        counts: b.counts,
+        validation: { inventory: true, content: true, query: true },
+    };
+    await store.upsert("main", [result]);
+    await atomic(join(state, "last-build.json"), {
+        artifact: b.directory,
+        version: result,
+    });
+    await rm(journalPath);
+    return result;
+}
+//# sourceMappingURL=publish.js.map

package/dist/publish.js.map

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

package/dist/releases.d.ts

@@ -0,0 +1,8 @@
+import { type Doc } from "./common.js";
+import { type CollectionStore } from "./remote.js";
+import { type Binding, type Published } from "./publish.js";
+export declare const releaseAlias: (ref: string) => string;
+export declare const releaseId: (ref: string) => string;
+/** Only observed local tags. Absence is not deletion authority; this command never prunes. */
+export declare function syncTags(store: CollectionStore, binding: Binding, path: string): Promise<Doc[]>;
+export declare function resolveVersion(store: CollectionStore, binding: Binding, selector: string): Promise<Published>;

package/dist/releases.js

@@ -0,0 +1,79 @@
+import { hash, invariant } from "./common.js";
+import { gitTags } from "./git.js";
+import { one, branch } from "./remote.js";
+import { published } from "./publish.js";
+export const releaseAlias = (ref) => `rel-${hash(ref).slice(0, 40)}`;
+export const releaseId = (ref) => `ref-${hash(ref)}`;
+/** Only observed local tags. Absence is not deletion authority; this command never prunes. */
+export async function syncTags(store, binding, path) {
+    const releases = await gitTags(path), versions = await published(store, binding), aliases = await store.aliases(), results = [];
+    for (const release of releases) {
+        const version = versions.find((v) => v.commitOid === release.oid);
+        const name = releaseAlias(release.ref);
+        let control = {
+            id: releaseId(release.ref),
+            kind: "manifest",
+            role: "git-ref",
+            schemaVersion: 1,
+            configHash: binding.configHash,
+            repoId: binding.repoId,
+            indexId: binding.indexId,
+            gitRef: release.ref,
+            desiredOid: release.oid,
+            aliasName: name,
+            status: "pending",
+        };
+        // Save moved-ref intent first so interrupted sync cannot expose the stale target as current.
+        await store.upsert("main", [control]);
+        if (version) {
+            const alias = aliases.find((a) => a.name === name);
+            if (!alias ||
+                alias.target !== version.tagName ||
+                alias.kind !== "TAG" ||
+                alias.dangling)
+                await store.alias(name, version.tagName, !!alias);
+            control = {
+                ...control,
+                status: "available",
+                tagName: version.tagName,
+                snapshotId: version.snapshotId,
+            };
+            await store.upsert("main", [control]);
+        }
+        results.push(control);
+    }
+    return results;
+}
+export async function resolveVersion(store, binding, selector) {
+    const versions = await published(store, binding);
+    const ref = selector.startsWith("refs/tags/")
+        ? selector
+        : `refs/tags/${selector}`;
+    const control = await one(store, branch("main"), releaseId(ref), true);
+    // Like Git import, a known tag name takes precedence over an OID spelling.
+    // Its pending or invalid state must not fall back to an unrelated commit.
+    if (!control && !selector.startsWith("refs/")) {
+        const direct = versions.filter((v) => v.commitOid === selector ||
+            v.tagName === selector ||
+            (/^[a-f0-9]{7,64}$/.test(selector) && v.commitOid.startsWith(selector)));
+        if (direct.length) {
+            invariant(direct.length === 1, "Ambiguous commit prefix.");
+            return direct[0];
+        }
+    }
+    invariant(control?.gitRef === ref &&
+        control.repoId === binding.repoId &&
+        control.indexId === binding.indexId &&
+        control.configHash === binding.configHash, "Version is not indexed or Git tag has not been synchronized.");
+    invariant(control.status === "available", "Git tag target is pending; import its desired commit and run git sync-tags.");
+    const alias = (await store.aliases()).find((a) => a.name === control.aliasName);
+    invariant(alias?.kind === "TAG" &&
+        !alias.dangling &&
+        alias.target === control.tagName, "Git tag Alias is out of sync; run git sync-tags.");
+    const result = versions.find((v) => v.commitOid === control.desiredOid &&
+        v.tagName === alias.target &&
+        v.snapshotId === control.snapshotId);
+    invariant(result, "Release target is not a published version.");
+    return result;
+}
+//# sourceMappingURL=releases.js.map

package/dist/releases.js.map

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

package/dist/remote.d.ts

@@ -0,0 +1,53 @@
+import { LambdaDBClient, type IndexConfigsUnion } from "@functional-systems/lambdadb";
+import { type Doc } from "./common.js";
+import type { Settings } from "./settings.js";
+export type Ref = {
+    kind: "branch" | "tag";
+    name: string;
+};
+export type Snapshot = {
+    name: string;
+    snapshotId: string;
+};
+export type Branch = {
+    name: string;
+    snapshotId: string | null;
+    parent: string | null;
+};
+export type Alias = {
+    name: string;
+    target: string;
+    kind: string;
+    dangling: boolean;
+};
+export type Hit = {
+    doc: Doc;
+    score?: number;
+};
+/** Narrow protocol boundary for fault-injection tests; LambdaDB is the only CLI backend. */
+export interface CollectionStore {
+    fetch(ref: Ref, ids: string[], consistent?: boolean): Promise<Doc[]>;
+    list(ref: Ref): AsyncIterable<Doc>;
+    upsert(branch: string, docs: Doc[]): Promise<void>;
+    delete(branch: string, ids: string[]): Promise<void>;
+    branches(): Promise<Branch[]>;
+    branch(name: string, source: string): Promise<void>;
+    tags(): Promise<Snapshot[]>;
+    tag(name: string, source: Ref): Promise<Snapshot>;
+    aliases(): Promise<Alias[]>;
+    alias(name: string, target: string, exists: boolean): Promise<void>;
+    query(tag: string, query: Record<string, unknown>, size: number): Promise<Hit[]>;
+}
+export declare class RemoteError extends Error {
+}
+export declare class LambdaRemote {
+    readonly settings: Settings;
+    readonly client: LambdaDBClient;
+    constructor(settings: Settings);
+    collections(): Promise<import("@functional-systems/lambdadb").CollectionResponseWithDates[]>;
+    create(name: string, indexConfigs: Record<string, IndexConfigsUnion>, description: string, tags: Record<string, string>): Promise<void>;
+    store(name: string): CollectionStore;
+}
+export declare const branch: (name: string) => Ref;
+export declare const tag: (name: string) => Ref;
+export declare function one(store: CollectionStore, ref: Ref, id: string, consistent?: boolean): Promise<Doc | undefined>;

package/dist/remote.js

@@ -0,0 +1,136 @@
+import { LambdaDBClient, branchRef, tagRef, branchSource, tagSource, tagTarget, } from "@functional-systems/lambdadb";
+import { invariant } from "./common.js";
+export class RemoteError extends Error {
+}
+async function request(operation, call) {
+    try {
+        return await call();
+    }
+    catch (e) {
+        // SDK errors can contain response bodies/source text. Never echo them or credentials.
+        const status = e.statusCode;
+        throw new RemoteError(`LambdaDB ${operation} failed${typeof status === "number" ? ` (HTTP ${status})` : ""}. Mutation outcome may be unknown; retain the retry journal.`, { cause: e });
+    }
+}
+export class LambdaRemote {
+    settings;
+    client;
+    constructor(settings) {
+        this.settings = settings;
+        const key = process.env[settings.apiKeyEnv];
+        invariant(key, `Missing environment variable ${settings.apiKeyEnv}.`);
+        this.client = new LambdaDBClient({
+            baseUrl: settings.endpoint,
+            projectName: settings.project,
+            projectApiKey: key,
+            retryConfig: { strategy: "none" },
+            timeoutMs: 30_000,
+        });
+    }
+    async collections() {
+        return request("list collections", async () => (await this.client.listAllCollections({ size: 100 })).collections);
+    }
+    async create(name, indexConfigs, description, tags) {
+        await request("create collection", () => this.client.createCollection({
+            collectionName: name,
+            indexConfigs,
+            description,
+            tags,
+        }));
+    }
+    store(name) {
+        const c = this.client.collection(name);
+        const ref = (r) => r.kind === "tag" ? tagRef(r.name) : branchRef(r.name);
+        return {
+            fetch: (r, ids, consistent = false) => request("fetch", async () => {
+                invariant(!consistent || r.kind === "branch", "Consistent reads require a Branch.");
+                const result = await c.docs.fetch(r.kind === "branch"
+                    ? {
+                        ref: branchRef(r.name),
+                        ids,
+                        consistentRead: consistent,
+                        includeVectors: true,
+                    }
+                    : {
+                        ref: tagRef(r.name),
+                        ids,
+                        consistentRead: false,
+                        includeVectors: true,
+                    });
+                return result.docs.map((d) => d.doc);
+            }),
+            async *list(r) {
+                let cursor;
+                const seen = new Set();
+                do {
+                    const page = await request("list documents", () => c.docs.list({
+                        ref: ref(r),
+                        size: 100,
+                        includeVectors: true,
+                        pageToken: cursor,
+                    }));
+                    for (const d of page.docs)
+                        yield d.doc;
+                    cursor = page.nextPageToken || undefined;
+                    if (cursor) {
+                        invariant(!seen.has(cursor), "LambdaDB repeated a pagination cursor.");
+                        seen.add(cursor);
+                    }
+                } while (cursor);
+            },
+            upsert: async (branch, docs) => {
+                await request("upsert", () => c.docs.upsert({ branch, docs }));
+            },
+            delete: async (branch, ids) => {
+                if (ids.length)
+                    await request("delete", () => c.docs.delete({ branch, ids }));
+            },
+            branches: () => request("list branches", async () => (await c.branches.list()).branches.map((b) => ({
+                name: b.name,
+                snapshotId: b.headSnapshot?.snapshotId ?? null,
+                parent: b.parentBranch?.name ?? null,
+            }))),
+            branch: async (name, source) => {
+                await request("create branch", () => c.branches.create({ branchName: name, source: branchSource(source) }));
+            },
+            tags: () => request("list tags", async () => (await c.tags.list()).tags.map((t) => ({
+                name: t.name,
+                snapshotId: t.snapshotId,
+            }))),
+            tag: (name, source) => request("create tag", async () => {
+                const t = (await c.tags.create({
+                    tagName: name,
+                    source: source.kind === "tag"
+                        ? tagSource(source.name)
+                        : branchSource(source.name),
+                })).tag;
+                return { name: t.name, snapshotId: t.snapshotId };
+            }),
+            aliases: () => request("list aliases", async () => (await c.aliases.list()).aliases.map((a) => ({
+                name: a.aliasName,
+                target: a.targetName,
+                kind: a.targetKind,
+                dangling: a.dangling,
+            }))),
+            alias: async (name, target, exists) => {
+                await request("set alias", () => exists
+                    ? c.aliases.retarget(name, { target: tagTarget(target) })
+                    : c.aliases.create({ aliasName: name, target: tagTarget(target) }));
+            },
+            query: (tag, query, size) => request("query", async () => (await c.query({
+                ref: tagRef(tag),
+                consistentRead: false,
+                query,
+                size,
+            })).docs.map((h) => ({ doc: h.doc, score: h.score }))),
+        };
+    }
+}
+export const branch = (name) => ({ kind: "branch", name });
+export const tag = (name) => ({ kind: "tag", name });
+export async function one(store, ref, id, consistent = false) {
+    const docs = await store.fetch(ref, [id], consistent);
+    invariant(docs.length <= 1 && docs.every((d) => d.id === id), "Unexpected fetch result.");
+    return docs[0];
+}
+//# sourceMappingURL=remote.js.map