@abseed/spectra-core 0.1.0

package/dist/schema.js

@@ -0,0 +1,222 @@
+/**
+ * Runtime validation for files a human may have edited by hand. The goal is a
+ * readable message pointing at the offending field, never a stack trace.
+ */
+import { z } from 'zod';
+import { TERM_TYPES } from './types.js';
+import { describeValueTypeError, isValueType } from './valueType.js';
+const termName = z
+    .string()
+    .min(1)
+    .regex(/^[A-Za-z_][A-Za-z0-9_]*$/, 'must be a bare identifier (letters, digits, underscore)');
+const valueType = z.string().superRefine((raw, ctx) => {
+    if (!isValueType(raw)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: describeValueTypeError(raw) });
+    }
+});
+/** Identity, stamped server-side. `.strict()` schemas below must allow it or a record carrying it is rejected. */
+const authorSchema = z
+    .object({
+    kind: z.enum(['human', 'spec', 'coder']),
+    user: z.string().min(1).optional(),
+})
+    .strict();
+/** Project identity, hand-editable in `specs/project.json`. Both fields are required and non-empty. */
+export const projectInfoSchema = z
+    .object({
+    name: z.string().min(1),
+    domain: z.string().min(1),
+})
+    .strict();
+export const attributeSchema = z
+    .object({
+    name: z.string().min(1),
+    valueType,
+    default: z.unknown().optional(),
+    optional: z.boolean().optional(),
+})
+    .strict();
+export const termSchema = z
+    .object({
+    name: termName,
+    type: z.enum(TERM_TYPES),
+    spec: z.string(),
+    parent: termName.nullable().default(null),
+    tags: z.array(z.string()).default([]),
+    attributes: z.array(attributeSchema).default([]),
+})
+    .strict();
+const opSchema = z.discriminatedUnion('op', [
+    z
+        .object({
+        op: z.literal('add_entity'),
+        term: termName,
+        termType: z.enum(TERM_TYPES).optional(),
+        parent: termName.nullable().optional(),
+        spec: z.string(),
+        tags: z.array(z.string()).optional(),
+        attributes: z.array(attributeSchema).optional(),
+    })
+        .strict(),
+    z.object({ op: z.literal('remove_entity'), term: termName }).strict(),
+    z.object({ op: z.literal('add_attribute'), term: termName, attribute: attributeSchema }).strict(),
+    z
+        .object({ op: z.literal('remove_attribute'), term: termName, attribute: z.string().min(1) })
+        .strict(),
+    z.object({ op: z.literal('modify_spec'), term: termName, spec: z.string() }).strict(),
+]);
+export const changesetSchema = z
+    .object({
+    id: z.string().min(1),
+    summary: z.string(),
+    ops: z.array(opSchema),
+    tests: z.array(z.string()).default([]),
+    fromQuestion: z.string().min(1).optional(),
+    appliedAt: z.string().optional(),
+    implementedAt: z.string().nullable().optional(),
+    author: authorSchema.optional(),
+})
+    .strict();
+export const proposalSchema = z
+    .object({
+    summary: z.string(),
+    ops: z.array(opSchema),
+    tests: z.array(z.string()).default([]),
+})
+    .strict();
+export const questionSchema = z
+    .object({
+    id: z.string().min(1),
+    asks: z.string().min(1),
+    because: z.string().min(1),
+    raisedBy: z
+        .object({
+        pass: z.string().min(1),
+        file: z.string().optional(),
+        terms: z.array(termName).default([]),
+    })
+        .strict(),
+    options: z
+        .array(z
+        .object({
+        label: z.string().min(1),
+        detail: z.string().optional(),
+        proposal: proposalSchema.nullable().default(null),
+    })
+        .strict())
+        .default([]),
+    author: authorSchema.optional(),
+    status: z.enum(['draft', 'ready']).default('ready'),
+    rev: z.number().int().positive().default(1),
+    answer: z
+        .object({
+        chose: z.string().nullable(),
+        note: z.string(),
+        answeredAt: z.string(),
+        changesetId: z.string().optional(),
+        author: authorSchema.optional(),
+    })
+        .strict()
+        .nullable()
+        .default(null),
+})
+    .strict()
+    .superRefine((question, ctx) => {
+    // An answer naming an option that does not exist would silently lose the decision.
+    const chose = question.answer?.chose;
+    if (chose && !question.options.some((option) => option.label === chose)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['answer', 'chose'],
+            message: `no option labelled "${chose}"`,
+        });
+    }
+});
+export const expectationSchema = z
+    .object({
+    id: z.string().min(1),
+    kind: z.enum(['functional', 'non-functional']),
+    author: authorSchema.optional(),
+    status: z.enum(['draft', 'ready']).default('ready'),
+    rev: z.number().int().positive().default(1),
+    terms: z.array(termName).default([]),
+    given: z.string().default(''),
+    expect: z.string().min(1),
+    raisedBy: z
+        .object({
+        pass: z.string().min(1),
+        from: z.string().min(1).optional(),
+        file: z.string().optional(),
+    })
+        .strict(),
+    supersededBy: z.string().min(1).nullable().default(null),
+    retiredBecause: z.string().min(1).optional(),
+    contested: z
+        .array(z
+        .object({
+        kind: z.enum(['unknown-term', 'duplicate', 'overlaps', 'contradicts', 'restates']),
+        subject: z.string().min(1),
+        detail: z.string().min(1),
+        quote: z.string().optional(),
+    })
+        .strict())
+        .default([]),
+})
+    .strict()
+    .superRefine((expectation, ctx) => {
+    // A functional expectation with no terms is coverage that can never be counted — it
+    // would sit in the file and show up against nothing. Non-functional ones are exempt:
+    // "the app survives a refresh" legitimately scopes to no term at all.
+    if (expectation.kind === 'functional' && expectation.terms.length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['terms'],
+            message: 'a functional expectation must name at least one glossary term',
+        });
+    }
+    // Self-supersession would make the expectation both live and retired, and the coverage
+    // pass would have to pick one.
+    if (expectation.supersededBy === expectation.id) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['supersededBy'],
+            message: 'an expectation cannot supersede itself',
+        });
+    }
+});
+function formatIssues(error) {
+    return error.issues.map((issue) => {
+        const path = issue.path.join('.');
+        return path ? `${path}: ${issue.message}` : issue.message;
+    });
+}
+export function parseTerm(data) {
+    const result = termSchema.safeParse(data);
+    return result.success
+        ? { ok: true, value: result.data }
+        : { ok: false, errors: formatIssues(result.error) };
+}
+export function parseChangeset(data) {
+    const result = changesetSchema.safeParse(data);
+    return result.success
+        ? { ok: true, value: result.data }
+        : { ok: false, errors: formatIssues(result.error) };
+}
+export function parseQuestion(data) {
+    const result = questionSchema.safeParse(data);
+    return result.success
+        ? { ok: true, value: result.data }
+        : { ok: false, errors: formatIssues(result.error) };
+}
+export function parseExpectation(data) {
+    const result = expectationSchema.safeParse(data);
+    return result.success
+        ? { ok: true, value: result.data }
+        : { ok: false, errors: formatIssues(result.error) };
+}
+export function parseProjectInfo(data) {
+    const result = projectInfoSchema.safeParse(data);
+    return result.success
+        ? { ok: true, value: result.data }
+        : { ok: false, errors: formatIssues(result.error) };
+}

package/dist/specStore.d.ts

@@ -0,0 +1,156 @@
+/**
+ * The storage seam for the glossary (GH #3).
+ *
+ * It lives in `@abseed/spectra-core`, the pure package, on purpose: this interface is the stable public
+ * boundary an out-of-repo store implements, and an implementor should depend on it without pulling
+ * in a server's Express/agent machinery. It references only domain types (from `./types.js` and
+ * `./schema.js`), so it belongs with them. The built-in filesystem and SQL backends live in
+ * `@abseed/spectra-server`; a hosted/networked backend is just another implementation of this contract.
+ *
+ * Why this exists: specs are a shared human artifact, not a byproduct of the code. To make
+ * them centrally visible to a team (and later multi-tenant/hosted), the content of `specs/`
+ * has to be able to live somewhere other than the local filesystem. This interface is the
+ * one place that decides *where*; `FileSystemSpecStore` (today's behaviour) and a future
+ * `SqlSpecStore` are peers behind it. "Hosted" is a deployment axis, not a third backend.
+ *
+ * The boundary, stated so we do not blur it:
+ *   - SpecStore is PERSISTENCE ONLY — reads, id allocation, and writes. Domain logic stays
+ *     in the caller: the changeset engine (`applyOps`), validation (`parseTerm`/…),
+ *     diagnostics, and version-guard decisions all remain in commit.ts / propose.ts /
+ *     answer.ts / raise.ts / expectations.ts, which compose a SpecStore rather than living
+ *     inside it.
+ *   - Records are addressed by DOMAIN ID (`term.name`, `changeset.id`, `q-…`, `e-…`). No
+ *     filename or path is used to *address* anything — the FS impl keeps its id→file map
+ *     private, which is what lets a SQL row id stand in with no change to the caller. The one
+ *     value that crosses the line is `StoredAt`, returned by the create methods purely so the
+ *     caller can echo "where it landed" in a response; it is opaque and never parsed.
+ *   - STATE IS DATA, NOT LOCATION. Today "applied" means a file sits in `applied/` and
+ *     "retired" means it sits in `retired/`; here those are state transitions named as
+ *     methods. The reads still return the partitioned view; only the FS impl backs it with
+ *     folders.
+ *   - `problems` survives: a record that will not load is reported, not thrown. It is an FS
+ *     truth today (hand-edited files) but an API backend can return partial data too. What
+ *     does NOT survive is "re-read from disk every call" — that is an FS detail.
+ *
+ * Not in scope: `data/transcripts.db` (chat history, its own store) and the version guard /
+ * `app/specs.snapshot.json` (tabled — a `version()` method belongs here eventually, once the
+ * snapshot is reworked into a queryable authority; deliberately left out of this first slice).
+ */
+import type { Answer, Changeset, Expectation, Op, ProjectInfo, Question, SourceProblem, Term } from './types.js';
+export interface Glossary {
+    terms: Term[];
+    problems: SourceProblem[];
+}
+export interface PendingChangesets {
+    changesets: Changeset[];
+    problems: SourceProblem[];
+    /**
+     * What has landed and what was turned down, newest first. Each entry is a distinct set of
+     * ops, so a changeset applied in two partial passes appears twice — the honest count.
+     */
+    applied: Changeset[];
+    rejected: Changeset[];
+}
+export interface QuestionFeed {
+    questions: Question[];
+    problems: SourceProblem[];
+}
+export interface ExpectationFeed {
+    /** Published, live expectations — what is currently expected to hold. Excludes drafts. */
+    expectations: Expectation[];
+    /**
+     * Drafts — live but not yet published, so they count toward nothing (coverage, the versioned
+     * contract, the agents' view) and are returned only for their author's own authoring UI.
+     */
+    drafts: Expectation[];
+    /** Superseded ones, kept so a test citing a retired id still resolves and the reason survives. */
+    retired: Expectation[];
+    problems: SourceProblem[];
+}
+/**
+ * Where the store put a newly created record. Opaque to callers — a filename for the
+ * filesystem backend, a row id for SQL — echoed back in responses, never parsed.
+ */
+export type StoredAt = string;
+/**
+ * One atomic application (#1, Trap 1). commit.ts runs the engine to produce the post-image,
+ * then hands the whole thing here as ONE call so the term writes and the pending→applied move
+ * commit together. On the filesystem this is the `writeAtomic` dance (which can half-land
+ * across files); on SQL it becomes a real transaction.
+ */
+export interface CommitApplication {
+    /** The pending changeset being (partially) applied. */
+    changesetId: string;
+    /** Full post-image of the glossary the engine produced — the store reconciles disk to this. */
+    nextTerms: Term[];
+    /** The ops that landed, recorded into the applied record. */
+    appliedOps: Op[];
+    /** Ops left unselected: they stay pending. Empty means the pending changeset is removed. */
+    remainingOps: Op[];
+    /** Caller's clock, so this stays testable. */
+    appliedAt: string;
+}
+/** What changed, in the store's own terms (filenames for FS, opaque strings for SQL). */
+export interface CommitResult {
+    written: string[];
+    deleted: string[];
+    /** Where the applied record now lives — the old relative-path `resolvedTo`, kept verbatim. */
+    resolvedTo: string;
+}
+/**
+ * The result of a mutation guarded by optimistic concurrency.
+ *
+ * `conflict` carries the revision the record is actually at, never a verdict — the caller
+ * compares it to what it expected, the same way `/api/specs/version` reports two numbers. When
+ * the caller supplies no `expectedRev`, the write proceeds and only ever returns `ok` or
+ * `not-found`; the conflict case appears only for a caller that opted into the check.
+ */
+export type MutationResult = {
+    ok: true;
+    rev: number;
+    at: StoredAt;
+} | {
+    ok: false;
+    reason: 'not-found';
+} | {
+    ok: false;
+    reason: 'conflict';
+    currentRev: number;
+};
+export interface SpecStore {
+    /**
+     * Who this glossary is — its display name and one-line domain. Glossary content, not
+     * deployment config: the filesystem backend reads it from `specs/project.json`, a SQL backend
+     * from a row, a hosted one per tenant. A missing or malformed source degrades to a neutral
+     * default rather than throwing, the same way an unreadable record becomes a `problem`.
+     */
+    projectInfo(): Promise<ProjectInfo>;
+    readTerms(): Promise<Glossary>;
+    readChangesets(): Promise<PendingChangesets>;
+    readQuestions(): Promise<QuestionFeed>;
+    readExpectations(): Promise<ExpectationFeed>;
+    findChangeset(id: string): Promise<Changeset | null>;
+    findQuestion(id: string): Promise<Question | null>;
+    findExpectation(id: string): Promise<Expectation | null>;
+    nextChangesetId(): Promise<string>;
+    nextQuestionId(): Promise<string>;
+    nextExpectationId(): Promise<string>;
+    addChangeset(changeset: Changeset): Promise<StoredAt>;
+    addQuestion(question: Question): Promise<StoredAt>;
+    addExpectation(expectation: Expectation): Promise<StoredAt>;
+    /** Atomic: reconcile terms to the post-image and move the changeset pending → applied. */
+    commitApplication(application: CommitApplication): Promise<CommitResult>;
+    /** Move a pending changeset to rejected. Returns where it landed, or null if none matched. */
+    rejectChangeset(id: string): Promise<string | null>;
+    /** Record code written against an applied changeset. Where it lives, or null if none matched. */
+    markImplemented(id: string, at: string): Promise<StoredAt | null>;
+    /**
+     * Write an answer into an open question (open → answered), in place, bumping its rev. When
+     * `expectedRev` is given and the question has moved past it, the write is refused as a conflict.
+     */
+    writeAnswer(questionId: string, answer: Answer, expectedRev?: number): Promise<MutationResult>;
+    /** Move a live expectation to retired (bumps its rev). `expectedRev` guards it, as above. */
+    retireExpectation(id: string, retired: Expectation, expectedRev?: number): Promise<MutationResult>;
+    /** Rewrite a live expectation in place, bumping its rev — e.g. after a recheck or a publish. */
+    rewriteExpectation(expectation: Expectation, expectedRev?: number): Promise<MutationResult>;
+}

package/dist/specStore.js

@@ -0,0 +1 @@
+export {};

package/dist/transcriptStore.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The storage seam for agent-conversation transcripts — the interface only.
+ *
+ * Like {@link SpecStore}, it lives in `@abseed/spectra-core`, the pure package, so an out-of-repo store can
+ * implement it without depending on a server's Express/agent machinery: the cloud backs it with D1,
+ * the open server with node:sqlite ({@link SqliteTranscriptStore} in `@abseed/spectra-server`), and both
+ * satisfy this one contract. The concrete backend, the plugin loader, and the on-disk defaults stay
+ * in the server; only the shape an implementor must match is here.
+ *
+ * Every read and write is async. A node:sqlite backend is synchronous underneath and resolves
+ * immediately, but the interface awaits because a store that talks to a database over the wire — the
+ * kind a multi-instance/hosted deploy needs — cannot answer synchronously, and the interface, not one
+ * backend, is the boundary implementors depend on. `close` is the one exception: tearing down a
+ * connection has nothing to await for a networked store.
+ *
+ * One instance serves every project, keyed by `projectId` per call (unlike SpecStore, which binds to
+ * one project): the runner is a long-lived singleton and sessions carry globally-unique ids, so only
+ * the operations that *scope* — creating and listing sessions — need the project; the rest resolve a
+ * session by its id.
+ */
+import type { AuthorKind } from './types.js';
+/**
+ * `tool_call` rows carry a status so a run interrupted mid-flight can be reasoned about later — on
+ * resume, a call left `started` may or may not have taken effect.
+ */
+export type EventKind = 'user' | 'assistant' | 'tool_call' | 'tool_result' | 'error' | 'approval';
+export type ToolStatus = 'started' | 'completed' | 'failed';
+export interface TranscriptEvent {
+    id: number;
+    sessionId: string;
+    /** Who produced the event — human or one of the agents. `kind` says what it is; this says who. */
+    author: AuthorKind;
+    kind: EventKind;
+    /** Plain text, kept searchable. For tool events, a one-line summary. */
+    text: string | null;
+    /** Structured detail as JSON — tool input/output, error causes. */
+    payload: unknown;
+    toolCallId: string | null;
+    status: ToolStatus | null;
+    createdAt: string;
+}
+export interface Session {
+    id: string;
+    /** The project this conversation belongs to. Sessions are listed and reached per project. */
+    projectId: string;
+    /**
+     * The user who owns this conversation, or `null` for an unattributed one. Sessions are per-user:
+     * a hosted deployment stamps the authenticated user here and lists each user only their own. On a
+     * single-user install there is no account, so it is `null` and listing is not narrowed — the owner
+     * of the durable record (who edited the glossary) lives on the changeset's `author.user`, not here.
+     */
+    ownerId: string | null;
+    title: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface NewEvent {
+    author: AuthorKind;
+    kind: EventKind;
+    text?: string | null;
+    payload?: unknown;
+    toolCallId?: string | null;
+    status?: ToolStatus | null;
+}
+export interface TranscriptStore {
+    createSession(id: string, projectId: string, ownerId: string | null, title: string, now: string): Promise<Session>;
+    renameSession(id: string, title: string, now: string): Promise<void>;
+    getSession(id: string): Promise<Session | null>;
+    /** Sessions for a project, newest first. `ownerId` narrows to one user's; omit it for all of them. */
+    listSessions(projectId: string, ownerId?: string, limit?: number): Promise<Session[]>;
+    append(sessionId: string, event: NewEvent, now: string): Promise<number>;
+    settleApproval(approvalId: string, decision: 'allow' | 'deny', note: string | null): Promise<void>;
+    readApproval(approvalId: string): Promise<TranscriptEvent | null>;
+    settleToolCall(toolCallId: string, status: ToolStatus, output: unknown): Promise<void>;
+    readToolCall(toolCallId: string): Promise<TranscriptEvent | null>;
+    read(sessionId: string, afterId?: number): Promise<TranscriptEvent[]>;
+    search(query: string, limit?: number): Promise<Array<TranscriptEvent & {
+        title: string;
+    }>>;
+    deleteSession(id: string): Promise<void>;
+    pruneBefore(before: string): Promise<number>;
+    close(): void;
+}

package/dist/transcriptStore.js

@@ -0,0 +1 @@
+export {};