@abseed/spectra-core 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Luke Pezet
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,6 @@
+Spectra
+Copyright 2026 Luke Pezet
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this project except in compliance with the License. You may obtain a copy of the
+License in the LICENSE file, or at http://www.apache.org/licenses/LICENSE-2.0

package/dist/answer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Answering a question, over the {@link SpecStore} seam.
+ *
+ * Two things happen and both matter: the answer is written back into the question, where it stays as
+ * the record of *why* the glossary says what it says, and the chosen option's proposal is minted into
+ * the pending changeset queue, where it goes through the same review the human already has. Nothing is
+ * applied — answering decides the intent; applying the changeset it produces is a separate act.
+ *
+ * Pure, so it lives in core beside the seam — every coordinator answers identically.
+ */
+import type { Answer, Author } from './types.js';
+import type { SpecStore } from './specStore.js';
+export type AnswerOutcome = {
+    ok: false;
+    status: 404;
+    error: string;
+} | {
+    ok: false;
+    status: 400;
+    error: string;
+} | {
+    ok: false;
+    status: 409;
+    error: string;
+} | {
+    ok: true;
+    questionId: string;
+    answer: Answer;
+    /** Set when the chosen option carried a proposal. */
+    changesetId?: string;
+    changesetFile?: string;
+};
+export interface AnswerRequest {
+    /** Label of the chosen option, or null to answer in prose without taking one. */
+    chose: string | null;
+    note: string;
+    /** ISO timestamp; the caller's clock, so this stays testable. */
+    answeredAt: string;
+}
+export declare function answerQuestion(store: SpecStore, id: string, request: AnswerRequest, author: Author): Promise<AnswerOutcome>;

package/dist/answer.js

@@ -0,0 +1,72 @@
+/** A short, filename-safe id fragment from an option label. Inlined so this stays free of I/O deps. */
+function slug(value) {
+    return (value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 48) || 'option');
+}
+export async function answerQuestion(store, id, request, author) {
+    const question = await store.findQuestion(id);
+    if (!question)
+        return { ok: false, status: 404, error: `No question with id "${id}".` };
+    // A decision is a record, not a setting. Changing your mind means a new question (or a
+    // hand-edit), so the reasoning that was acted on cannot be quietly overwritten.
+    if (question.answer) {
+        return {
+            ok: false,
+            status: 409,
+            error: `"${id}" was already answered on ${question.answer.answeredAt}. Raise a new question rather than overwriting the decision.`,
+        };
+    }
+    const option = request.chose === null
+        ? null
+        : question.options.find((candidate) => candidate.label === request.chose);
+    if (request.chose !== null && !option) {
+        return { ok: false, status: 400, error: `"${id}" has no option labelled "${request.chose}".` };
+    }
+    if (request.chose === null && !request.note.trim()) {
+        return {
+            ok: false,
+            status: 400,
+            error: 'Answering without choosing an option requires a note saying what to do instead.',
+        };
+    }
+    const answer = {
+        chose: request.chose,
+        note: request.note,
+        answeredAt: request.answeredAt,
+        author,
+    };
+    let changesetFile;
+    if (option?.proposal) {
+        const changesetId = `${question.id}-${slug(option.label)}`;
+        const changeset = {
+            id: changesetId,
+            summary: option.proposal.summary,
+            ops: option.proposal.ops,
+            tests: option.proposal.tests,
+            fromQuestion: question.id,
+            author,
+        };
+        // Written before the answer: if the process dies between the two, an unreferenced changeset
+        // in the queue is noise someone notices, where an answer citing a changeset that was never
+        // written is a dangling reference.
+        changesetFile = await store.addChangeset(changeset);
+        answer.changesetId = changesetId;
+    }
+    // No expectedRev here: a question's one mutation is being answered, and the "already answered"
+    // guard above is that record's optimistic-concurrency check. writeAnswer still bumps the rev.
+    const written = await store.writeAnswer(id, answer);
+    if (!written.ok) {
+        // Only 'not-found' is reachable without an expectedRev — the question vanished mid-answer.
+        return { ok: false, status: 404, error: `No question with id "${id}".` };
+    }
+    return {
+        ok: true,
+        questionId: question.id,
+        answer,
+        ...(answer.changesetId ? { changesetId: answer.changesetId } : {}),
+        ...(changesetFile ? { changesetFile } : {}),
+    };
+}

package/dist/backlinks.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The glossary's edges, derived rather than stored. Nothing in a term file records
+ * "who points at me" — it is recomputed from `parent` and `ref:` attribute types on
+ * every read, so a hand-edit can never leave a stale backlink behind.
+ */
+import type { Term } from './types.js';
+export type ReferenceKind = 'parent' | 'attribute';
+export interface Reference {
+    /** The term doing the referencing. */
+    from: string;
+    /** The term name being referenced — may not exist, see `dangling`. */
+    to: string;
+    kind: ReferenceKind;
+    /** The attribute carrying the reference, or null for an `is-a` edge. */
+    via: string | null;
+    array: boolean;
+}
+export interface Backlinks {
+    references: Reference[];
+    /** Edges pointing *at* a term, keyed by target name. */
+    byTarget: Record<string, Reference[]>;
+    /** Edges pointing *out of* a term, keyed by source name. */
+    bySource: Record<string, Reference[]>;
+    /** Subtypes, keyed by supertype name. */
+    children: Record<string, string[]>;
+    /** Edges whose target does not exist in the glossary. */
+    dangling: Reference[];
+}
+export declare function computeBacklinks(terms: Term[]): Backlinks;
+export type HighlightKind = 'selected' | 'parent' | 'child' | 'referrer' | 'referenced';
+/**
+ * Everything connected to `name`, in either direction, labelled by how. Drives
+ * click-a-term-to-highlight-what-it-touches — the search-first stand-in for wires.
+ */
+export declare function connectionsFor(backlinks: Backlinks, name: string): Map<string, HighlightKind>;

package/dist/backlinks.js

@@ -0,0 +1,66 @@
+import { parseValueType } from './valueType.js';
+export function computeBacklinks(terms) {
+    const known = new Set(terms.map((term) => term.name));
+    const references = [];
+    for (const term of terms) {
+        if (term.parent) {
+            references.push({ from: term.name, to: term.parent, kind: 'parent', via: null, array: false });
+        }
+        for (const attribute of term.attributes) {
+            const parsed = parseValueType(attribute.valueType);
+            if (parsed?.kind === 'ref') {
+                references.push({
+                    from: term.name,
+                    to: parsed.name,
+                    kind: 'attribute',
+                    via: attribute.name,
+                    array: parsed.array,
+                });
+            }
+        }
+    }
+    const byTarget = {};
+    const bySource = {};
+    const children = {};
+    for (const reference of references) {
+        ;
+        (byTarget[reference.to] ??= []).push(reference);
+        (bySource[reference.from] ??= []).push(reference);
+        if (reference.kind === 'parent') {
+            ;
+            (children[reference.to] ??= []).push(reference.from);
+        }
+    }
+    return {
+        references,
+        byTarget,
+        bySource,
+        children,
+        dangling: references.filter((reference) => !known.has(reference.to)),
+    };
+}
+/**
+ * Everything connected to `name`, in either direction, labelled by how. Drives
+ * click-a-term-to-highlight-what-it-touches — the search-first stand-in for wires.
+ */
+export function connectionsFor(backlinks, name) {
+    const connections = new Map();
+    // Weakest first: later writes win, so `selected` and is-a edges beat plain references.
+    for (const reference of backlinks.bySource[name] ?? []) {
+        if (reference.kind === 'attribute')
+            connections.set(reference.to, 'referenced');
+    }
+    for (const reference of backlinks.byTarget[name] ?? []) {
+        if (reference.kind === 'attribute')
+            connections.set(reference.from, 'referrer');
+    }
+    for (const reference of backlinks.bySource[name] ?? []) {
+        if (reference.kind === 'parent')
+            connections.set(reference.to, 'parent');
+    }
+    for (const child of backlinks.children[name] ?? []) {
+        connections.set(child, 'child');
+    }
+    connections.set(name, 'selected');
+    return connections;
+}

package/dist/changeset.d.ts

@@ -0,0 +1,25 @@
+import type { Diagnostic, Op, Term } from './types.js';
+export type OpKindClass = 'add' | 'remove' | 'modify';
+export interface OpEffect {
+    index: number;
+    op: Op;
+    kind: OpKindClass;
+    term: string;
+    /** Target term immediately before this op, or null if it did not exist yet. */
+    before: Term | null;
+    /** Target term immediately after. Equal to `before` when the op failed. */
+    after: Term | null;
+    ok: boolean;
+}
+export interface ApplyResult {
+    terms: Term[];
+    diagnostics: Diagnostic[];
+    effects: OpEffect[];
+}
+export declare function opKindClass(op: Op): OpKindClass;
+export declare function applyOps(terms: Term[], ops: Op[]): ApplyResult;
+export declare function validateOps(terms: Term[], ops: Op[]): Diagnostic[];
+export declare function hasErrors(diagnostics: Diagnostic[]): boolean;
+export declare function hasWarnings(diagnostics: Diagnostic[]): boolean;
+/** One-line human summary of an op, for the review list. */
+export declare function summarizeOp(op: Op): string;

package/dist/changeset.js

@@ -0,0 +1,157 @@
+/**
+ * Replaying changeset ops against the glossary. Pure — no filesystem — so the web app
+ * can preview exactly what the server will commit, and both agree on what counts as
+ * broken. Ops are applied in order and each one can fail independently; a failed op is
+ * skipped rather than aborting the run, so the UI can show every problem at once.
+ */
+import { computeBacklinks } from './backlinks.js';
+export function opKindClass(op) {
+    switch (op.op) {
+        case 'add_entity':
+        case 'add_attribute':
+            return 'add';
+        case 'remove_entity':
+        case 'remove_attribute':
+            return 'remove';
+        case 'modify_spec':
+            return 'modify';
+    }
+}
+function referenceKey(reference) {
+    return `${reference.from}|${reference.via ?? ''}|${reference.to}`;
+}
+function edgeKey(from, via) {
+    return `${from}|${via ?? ''}`;
+}
+function describeEdge(reference) {
+    return reference.via ? `${reference.from}.${reference.via}` : `${reference.from}'s parent`;
+}
+export function applyOps(terms, ops) {
+    const byName = new Map(terms.map((term) => [term.name, structuredClone(term)]));
+    const diagnostics = [];
+    const effects = [];
+    /** Edges this op selection creates, so a dangling one can be blamed on the op that made it. */
+    const introduced = new Map();
+    const snapshot = (name) => {
+        const term = byName.get(name);
+        return term ? structuredClone(term) : null;
+    };
+    ops.forEach((op, index) => {
+        const before = snapshot(op.term);
+        const kind = opKindClass(op);
+        const fail = (message) => {
+            diagnostics.push({ opIndex: index, severity: 'error', message });
+            effects.push({ index, op, kind, term: op.term, before, after: before, ok: false });
+        };
+        const done = () => {
+            effects.push({ index, op, kind, term: op.term, before, after: snapshot(op.term), ok: true });
+        };
+        switch (op.op) {
+            case 'add_entity': {
+                if (byName.has(op.term))
+                    return fail(`"${op.term}" already exists.`);
+                const created = {
+                    name: op.term,
+                    type: op.termType ?? 'entity',
+                    spec: op.spec,
+                    parent: op.parent ?? null,
+                    tags: op.tags ?? [],
+                    attributes: op.attributes ?? [],
+                };
+                byName.set(op.term, created);
+                if (created.parent)
+                    introduced.set(edgeKey(op.term, null), index);
+                for (const attribute of created.attributes) {
+                    introduced.set(edgeKey(op.term, attribute.name), index);
+                }
+                return done();
+            }
+            case 'remove_entity': {
+                if (!byName.has(op.term))
+                    return fail(`"${op.term}" does not exist.`);
+                byName.delete(op.term);
+                return done();
+            }
+            case 'add_attribute': {
+                const target = byName.get(op.term);
+                if (!target)
+                    return fail(`"${op.term}" does not exist.`);
+                if (target.attributes.some((existing) => existing.name === op.attribute.name)) {
+                    return fail(`"${op.term}" already has an attribute named "${op.attribute.name}".`);
+                }
+                target.attributes.push(structuredClone(op.attribute));
+                introduced.set(edgeKey(op.term, op.attribute.name), index);
+                return done();
+            }
+            case 'remove_attribute': {
+                const target = byName.get(op.term);
+                if (!target)
+                    return fail(`"${op.term}" does not exist.`);
+                const at = target.attributes.findIndex((existing) => existing.name === op.attribute);
+                if (at === -1)
+                    return fail(`"${op.term}" has no attribute named "${op.attribute}".`);
+                target.attributes.splice(at, 1);
+                return done();
+            }
+            case 'modify_spec': {
+                const target = byName.get(op.term);
+                if (!target)
+                    return fail(`"${op.term}" does not exist.`);
+                target.spec = op.spec;
+                return done();
+            }
+        }
+    });
+    const result = [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+    // Only edges this selection *newly* breaks are its problem — a glossary that was
+    // already broken by hand stays broken without blaming the changeset for it.
+    const alreadyDangling = new Set(computeBacklinks(terms).dangling.map(referenceKey));
+    for (const reference of computeBacklinks(result).dangling) {
+        if (alreadyDangling.has(referenceKey(reference)))
+            continue;
+        const culprit = introduced.get(edgeKey(reference.from, reference.via));
+        if (culprit !== undefined) {
+            // The selection adds a reference to something it never creates — usually a
+            // cherry-pick that left its dependency behind. Nothing to acknowledge; it is wrong.
+            diagnostics.push({
+                opIndex: culprit,
+                severity: 'error',
+                message: `${describeEdge(reference)} references "${reference.to}", which does not exist. The op that creates it is not part of this selection.`,
+            });
+        }
+        else {
+            // A reference that was fine until this selection removed its target. Real, but the
+            // human may mean it — surface it and make them say so.
+            diagnostics.push({
+                opIndex: null,
+                severity: 'warning',
+                message: `${describeEdge(reference)} references "${reference.to}", which this change removes.`,
+            });
+        }
+    }
+    return { terms: result, diagnostics, effects };
+}
+export function validateOps(terms, ops) {
+    return applyOps(terms, ops).diagnostics;
+}
+export function hasErrors(diagnostics) {
+    return diagnostics.some((diagnostic) => diagnostic.severity === 'error');
+}
+export function hasWarnings(diagnostics) {
+    return diagnostics.some((diagnostic) => diagnostic.severity === 'warning');
+}
+/** One-line human summary of an op, for the review list. */
+export function summarizeOp(op) {
+    switch (op.op) {
+        case 'add_entity':
+            return `add ${op.termType ?? 'entity'} ${op.term}${op.parent ? ` (is-a ${op.parent})` : ''}`;
+        case 'remove_entity':
+            return `remove ${op.term}`;
+        case 'add_attribute':
+            return `add ${op.term}.${op.attribute.name}: ${op.attribute.valueType}`;
+        case 'remove_attribute':
+            return `remove ${op.term}.${op.attribute}`;
+        case 'modify_spec':
+            return `rewrite the spec of ${op.term}`;
+    }
+}

package/dist/commit.d.ts

@@ -0,0 +1,42 @@
+import type { Diagnostic } from './types.js';
+import type { SpecStore } from './specStore.js';
+export type CommitOutcome = {
+    ok: false;
+    status: 404;
+    error: string;
+} | {
+    ok: false;
+    status: 400;
+    error: string;
+} | {
+    ok: false;
+    status: 409;
+    error: string;
+    diagnostics: Diagnostic[];
+    needsAcknowledgement: boolean;
+} | {
+    ok: true;
+    appliedOps: number;
+    remainingOps: number;
+    written: string[];
+    deleted: string[];
+    resolvedTo: string;
+    diagnostics: Diagnostic[];
+};
+export interface ApplyRequest {
+    opIndices: number[];
+    acknowledgeWarnings?: boolean;
+}
+export declare function applyChangeset(store: SpecStore, id: string, request: ApplyRequest): Promise<CommitOutcome>;
+/**
+ * Records that code has been written for an applied changeset — the human presses a button after
+ * re-running the implementation pass. (The agent's own `mark_implemented` tool guards this with a
+ * snapshot version; this human path just records it.)
+ */
+export declare function markImplemented(store: SpecStore, id: string, at: string): Promise<{
+    ok: boolean;
+    status?: number;
+    error?: string;
+    file?: string;
+}>;
+export declare function rejectChangeset(store: SpecStore, id: string): Promise<CommitOutcome>;