@abseed/spectra-core 0.1.0

package/dist/expectations.js

@@ -0,0 +1,114 @@
+/**
+ * Writing expectations, over the {@link SpecStore} seam — governed asymmetrically, and the asymmetry
+ * is the design.
+ *
+ * **Adding is free.** A new expectation changes no term and cannot alter what the app does; the most
+ * it can do is turn a check red, which reveals a defect rather than hiding one — safe by construction,
+ * the way `raiseQuestion` is. **Weakening is reviewed.** Superseding replaces a statement someone
+ * relies on — the one move that can turn a red check green without touching code — so it does not
+ * happen in place: the old expectation keeps its id, gains `supersededBy`, and moves to retired.
+ *
+ * Pure (the semantic re-check is *injected*, never called here), so it lives in core beside the seam:
+ * every coordinator raises, publishes, rechecks and supersedes identically.
+ */
+import { parseExpectation } from './schema.js';
+/** Maps a store mutation onto an ExpectationOutcome — not-found → 404, a stale rev → 409. */
+function fromMutation(id, result, written) {
+    if (result.ok)
+        return { ok: true, id, file: result.at, expectation: { ...written, rev: result.rev } };
+    if (result.reason === 'not-found')
+        return { ok: false, error: `No live expectation "${id}".`, status: 404 };
+    return {
+        ok: false,
+        status: 409,
+        error: `"${id}" moved since you last read it — it is now at revision ${result.currentRev}.`,
+        currentRev: result.currentRev,
+    };
+}
+export async function raiseExpectation(store, request, author) {
+    const id = await store.nextExpectationId();
+    const expectation = {
+        id,
+        kind: request.kind,
+        author,
+        status: request.status ?? 'ready',
+        rev: 1,
+        terms: request.terms,
+        given: request.given ?? '',
+        expect: request.expect,
+        raisedBy: {
+            pass: request.pass,
+            ...(request.from ? { from: request.from } : {}),
+            ...(request.file ? { file: request.file } : {}),
+        },
+        supersededBy: null,
+        contested: request.contested ?? [],
+    };
+    // Validated before it reaches disk, not after — an invalid expectation would otherwise come
+    // back as a source problem in the UI instead of an error the caller can act on.
+    const parsed = parseExpectation(expectation);
+    if (!parsed.ok)
+        return { ok: false, error: parsed.errors.join('; '), status: 400 };
+    const file = await store.addExpectation(expectation);
+    return { ok: true, id, file, expectation };
+}
+/**
+ * Publish a draft expectation — draft → ready. A draft counts toward nothing; publishing puts it into
+ * coverage and the versioned contract. Rewrites in place, keeping its id and file. Idempotent.
+ */
+export async function publishExpectation(store, id, expectedRev) {
+    const expectation = await store.findExpectation(id);
+    if (!expectation)
+        return { ok: false, error: `No live expectation "${id}".`, status: 404 };
+    const updated = { ...expectation, status: 'ready' };
+    return fromMutation(id, await store.rewriteExpectation(updated, expectedRev), updated);
+}
+/**
+ * Re-reads a live expectation against the specs as they are now, and rewrites what it clashes with.
+ * The `check` is injected — a coordinator provides how a clash is found (a model pass, or the core
+ * checks only). It never retires anything: if the disagreement survives, the expectation stays live
+ * and contested and a human decides.
+ */
+export async function recheckExpectation(store, id, check, expectedRev) {
+    const expectation = await store.findExpectation(id);
+    if (!expectation)
+        return { ok: false, error: `No live expectation "${id}".`, status: 404 };
+    const { expectations } = await store.readExpectations();
+    const others = expectations.filter((candidate) => candidate.id !== id);
+    const contested = await check(expectation, others);
+    const updated = { ...expectation, contested };
+    return fromMutation(id, await store.rewriteExpectation(updated, expectedRev), updated);
+}
+/**
+ * Retire an expectation, optionally replacing it. The replacement is written first and the original
+ * moved second, so a crash between them leaves a duplicate-looking pair rather than a gap.
+ */
+export async function supersedeExpectation(store, id, request, author, expectedRev) {
+    const original = await store.findExpectation(id);
+    if (!original)
+        return { ok: false, error: `No live expectation "${id}".`, status: 404 };
+    let replacement = null;
+    if (request.replacement) {
+        const raised = await raiseExpectation(store, { ...request.replacement, pass: request.replacement.pass ?? 'supersedes', from: id }, author);
+        if (!raised.ok)
+            return { ok: false, error: raised.error, status: raised.status ?? 400 };
+        replacement = raised.expectation;
+    }
+    const retired = {
+        ...original,
+        supersededBy: replacement?.id ?? null,
+        retiredBecause: request.note,
+    };
+    const moved = await store.retireExpectation(id, retired, expectedRev);
+    if (!moved.ok) {
+        if (moved.reason === 'not-found')
+            return { ok: false, error: `No live expectation "${id}".`, status: 404 };
+        return {
+            ok: false,
+            status: 409,
+            error: `"${id}" moved since you last read it — it is now at revision ${moved.currentRev}.`,
+            currentRev: moved.currentRev,
+        };
+    }
+    return { ok: true, retired: id, replacement };
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export * from './types.js';
+export * from './valueType.js';
+export * from './schema.js';
+export * from './backlinks.js';
+export * from './changeset.js';
+export * from './conflicts.js';
+export * from './coverage.js';
+export * from './expectationCheck.js';
+export * from './specStore.js';
+export * from './transcriptStore.js';
+export * from './propose.js';
+export * from './raise.js';
+export * from './commit.js';
+export * from './answer.js';
+export * from './expectations.js';

package/dist/index.js

@@ -0,0 +1,15 @@
+export * from './types.js';
+export * from './valueType.js';
+export * from './schema.js';
+export * from './backlinks.js';
+export * from './changeset.js';
+export * from './conflicts.js';
+export * from './coverage.js';
+export * from './expectationCheck.js';
+export * from './specStore.js';
+export * from './transcriptStore.js';
+export * from './propose.js';
+export * from './raise.js';
+export * from './commit.js';
+export * from './answer.js';
+export * from './expectations.js';

package/dist/propose.d.ts

@@ -0,0 +1,19 @@
+import type { Author, Changeset, Op } from './types.js';
+import type { SpecStore } from './specStore.js';
+export interface ProposeRequest {
+    summary: string;
+    ops: Op[];
+    tests: string[];
+    /** Set when the proposal follows from a question that has already been answered. */
+    fromQuestion?: string;
+}
+export type ProposeOutcome = {
+    ok: false;
+    error: string;
+} | {
+    ok: true;
+    id: string;
+    file: string;
+    changeset: Changeset;
+};
+export declare function proposeChangeset(store: SpecStore, request: ProposeRequest, author: Author): Promise<ProposeOutcome>;

package/dist/propose.js

@@ -0,0 +1,32 @@
+/**
+ * Minting a changeset — the canonical write, over the {@link SpecStore} seam.
+ *
+ * It lives in `@abseed/spectra-core` for the same reason the seam interfaces do: it is pure (it validates a
+ * request and writes through the store, with no server, filesystem, or SDK dependency), and both the
+ * open server and an out-of-repo backend need to propose *identically*. Keeping it beside the seam is
+ * what makes "propose a changeset" one operation with one meaning, whichever process runs it.
+ *
+ * Safe for the same reason `raiseQuestion` is: a changeset lands in the pending queue and changes
+ * *nothing*. It still has to be reviewed and applied through the same panel, with the same diff
+ * preview and conflict detection. "Writes a file" is not "changes the glossary", so this needs no
+ * approval prompt of its own — the approval already exists downstream.
+ */
+import { parseChangeset } from './schema.js';
+export async function proposeChangeset(store, request, author) {
+    const id = await store.nextChangesetId();
+    const changeset = {
+        id,
+        summary: request.summary,
+        ops: request.ops,
+        tests: request.tests,
+        ...(request.fromQuestion ? { fromQuestion: request.fromQuestion } : {}),
+        author,
+    };
+    // Validate before writing: a malformed changeset on disk comes back as a source problem in
+    // the UI, which is a worse way to learn about it than a message here.
+    const parsed = parseChangeset(changeset);
+    if (!parsed.ok)
+        return { ok: false, error: parsed.errors.join('; ') };
+    const file = await store.addChangeset(changeset);
+    return { ok: true, id, file, changeset };
+}

package/dist/raise.d.ts

@@ -0,0 +1,26 @@
+import type { Author, Proposal, Question, RecordStatus } from './types.js';
+import type { SpecStore } from './specStore.js';
+export interface RaiseRequest {
+    asks: string;
+    because: string;
+    pass: string;
+    file?: string;
+    terms: string[];
+    options: Array<{
+        label: string;
+        detail?: string;
+        proposal?: Proposal | null;
+    }>;
+    /** Draft or published. Absent means `ready`; agents always raise `ready`. */
+    status?: RecordStatus;
+}
+export type RaiseOutcome = {
+    ok: false;
+    error: string;
+} | {
+    ok: true;
+    id: string;
+    file: string;
+    question: Question;
+};
+export declare function raiseQuestion(store: SpecStore, request: RaiseRequest, author: Author): Promise<RaiseOutcome>;

package/dist/raise.js

@@ -0,0 +1,42 @@
+/**
+ * Raising a question — the one write an agent is allowed to make against the glossary, over the
+ * {@link SpecStore} seam.
+ *
+ * Like {@link proposeChangeset}, it lives in `@abseed/spectra-core` because it is pure and both the open
+ * server and an out-of-repo backend must raise a question identically — one operation, one meaning.
+ *
+ * Safe by construction: a question changes no term and applies no op. It is a request for a decision,
+ * and every path out of it (answering, then reviewing the changeset it mints) still runs through the
+ * human. That is why this needs no approval prompt while `proposeChangeset` will.
+ */
+import { parseQuestion } from './schema.js';
+export async function raiseQuestion(store, request, author) {
+    const id = await store.nextQuestionId();
+    const options = request.options.map((option) => ({
+        label: option.label,
+        ...(option.detail ? { detail: option.detail } : {}),
+        proposal: option.proposal ?? null,
+    }));
+    const question = {
+        id,
+        asks: request.asks,
+        because: request.because,
+        raisedBy: {
+            pass: request.pass,
+            ...(request.file ? { file: request.file } : {}),
+            terms: request.terms,
+        },
+        author,
+        status: request.status ?? 'ready',
+        rev: 1,
+        options,
+        answer: null,
+    };
+    // Validate before writing rather than after: a malformed question would otherwise land on
+    // disk and come back as a source problem in the UI.
+    const parsed = parseQuestion(question);
+    if (!parsed.ok)
+        return { ok: false, error: parsed.errors.join('; ') };
+    const file = await store.addQuestion(question);
+    return { ok: true, id, file, question };
+}