@abseed/spectra-core 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,299 @@
+/**
+ * The glossary schema. These types are the contract between the human authoring
+ * specs in the UI and the AI agent that implements them — everything else in this
+ * repo is a view over data shaped like this.
+ */
+/**
+ * Who made a write. The kind distinguishes a person from the two agents; it is stamped
+ * server-side from the route or the agent definition, never taken from the client, so an actor
+ * in the sandbox cannot claim to be a human. `user` is the human account — absent until auth
+ * exists, and for an agent action it is eventually the human whose session it was.
+ *
+ * This is identity, kept separate from the `raisedBy` origin (which records *why* and in what
+ * pass). Optional on the records below: absent means the record predates identity tracking,
+ * the same way `appliedAt` is absent on changesets applied before it was recorded.
+ */
+export type AuthorKind = 'human' | 'spec' | 'coder';
+export interface Author {
+    kind: AuthorKind;
+    user?: string;
+}
+/**
+ * Whether a human-authored artifact is still being drafted or has been published to the team.
+ *
+ * `ready` is the published state — it counts as coverage, rides in the versioned contract, and
+ * the agents see it. `draft` is author-only and part of nothing until it is published, the same
+ * way a draft PR is not yet a request for review. Optional on the records below: absent means
+ * `ready`, so the specs already on disk (all published) need no rewrite. Agents always raise
+ * `ready`; drafting is a human convenience.
+ */
+export type RecordStatus = 'draft' | 'ready';
+/**
+ * Who this glossary is, in one place. `name` is the display title (the UI header) and what the
+ * agents are told they are working on; `domain` is a one-line description of the subject the
+ * glossary describes — the framing an agent reads before it has read a single term.
+ *
+ * This is glossary *content*, not deployment config: it describes the project itself, so it is
+ * retrieved through the SpecStore (a file for the filesystem backend, a row for SQL, per-tenant
+ * once hosted) rather than baked into a prompt string. The *link* to a hosted project — endpoint,
+ * project id, credentials — is a separate, bootstrap concern and does not live here.
+ */
+export interface ProjectInfo {
+    name: string;
+    domain: string;
+}
+export type TermType = 'entity' | 'event' | 'function' | 'attribute-type';
+export declare const TERM_TYPES: readonly TermType[];
+export interface Attribute {
+    name: string;
+    /** A primitive (`string`, `number`, `boolean`, `date`) or `ref:<TermName>`, either with an optional `[]` suffix. */
+    valueType: string;
+    default?: unknown;
+    optional?: boolean;
+}
+export interface Term {
+    name: string;
+    type: TermType;
+    /** Short natural-language description — spec-worthy, precise enough to generate tests from. */
+    spec: string;
+    /** Single supertype (is-a), or null. */
+    parent: string | null;
+    /** Free cross-cutting labels; not a hierarchy. */
+    tags: string[];
+    attributes: Attribute[];
+}
+/** How the AI (or a hand-authored fixture) proposes an edit: structured ops, never free text. */
+export type Op = {
+    op: 'add_entity';
+    term: string;
+    /** Defaults to `entity`; carries the other kinds so one op can add functions and events too. */
+    termType?: TermType;
+    parent?: string | null;
+    spec: string;
+    tags?: string[];
+    attributes?: Attribute[];
+} | {
+    op: 'remove_entity';
+    term: string;
+} | {
+    op: 'add_attribute';
+    term: string;
+    attribute: Attribute;
+} | {
+    op: 'remove_attribute';
+    term: string;
+    attribute: string;
+} | {
+    op: 'modify_spec';
+    term: string;
+    spec: string;
+};
+export type OpKind = Op['op'];
+export interface Changeset {
+    id: string;
+    summary: string;
+    ops: Op[];
+    /** Plain-language test intentions; a changeset carrying passing tests is safer to auto-approve. */
+    tests: string[];
+    /** Who proposed it. Absent on changesets minted before identity was tracked. */
+    author?: Author;
+    /** Set when this changeset was minted by answering a Question — the id of that question. */
+    fromQuestion?: string;
+    /** ISO timestamp, written when the changeset lands. Absent while it is still pending. */
+    appliedAt?: string;
+    /**
+     * When code was written for this change. `null` means applied but not yet implemented —
+     * the state the `implements:` markers cannot detect, because a rewritten spec leaves
+     * every marker looking correct. Absent on changesets applied before this was tracked.
+     */
+    implementedAt?: string | null;
+}
+/**
+ * A question raised against the glossary — normally by an agent that tried to implement
+ * it and hit something the specs do not settle.
+ *
+ * The unit here is deliberately a *question*, not a "finding": if an entry cannot be
+ * phrased as something the human answers, it does not belong in the queue. That rules out
+ * the observations an implementation pass would otherwise flood it with, and it keeps the
+ * agent from quietly making product decisions by dressing a guess up as a proposal.
+ */
+export interface Question {
+    id: string;
+    /** The question itself, answerable as written. */
+    asks: string;
+    /** Why it is being asked — must quote the spec text in conflict, not just describe inconvenience. */
+    because: string;
+    raisedBy: QuestionOrigin;
+    /** Who raised it. Absent on questions raised before identity was tracked. */
+    author?: Author;
+    /** Draft or published. Absent means `ready`. Agent-raised questions are always `ready`. */
+    status?: RecordStatus;
+    /**
+     * Bumped by the store on every write. A caller that read revision N can send it back as the
+     * expected revision on its next write; the store refuses if the record has moved since. Absent
+     * means 1 — the birth value and what a record predating this reads as.
+     */
+    rev?: number;
+    /**
+     * Candidate answers. The count is the answer shape, so there is no separate field to
+     * keep in sync: one option is approve-or-decline, several is a choice, none means only
+     * the human can write the spec text.
+     */
+    options: QuestionOption[];
+    /** Null while open. Kept after answering — the reasoning outlives the changeset. */
+    answer: Answer | null;
+}
+export interface QuestionOrigin {
+    /** What was being done when it came up, e.g. `implementation`. */
+    pass: string;
+    file?: string;
+    /** Terms the question is about, so it can be shown against them in the glossary. */
+    terms: string[];
+}
+export interface QuestionOption {
+    label: string;
+    /** The tradeoff in plain language, including what answering this way costs. */
+    detail?: string;
+    /** What would go into the pending queue. Null when this option changes no specs. */
+    proposal: Proposal | null;
+}
+/** A changeset body without an id — the id is minted when the option is chosen. */
+export interface Proposal {
+    summary: string;
+    ops: Op[];
+    tests: string[];
+}
+export interface Answer {
+    /** Label of the chosen option, or null when the human answered without taking one. */
+    chose: string | null;
+    note: string;
+    /** ISO timestamp. */
+    answeredAt: string;
+    /** Id of the changeset this answer put into the pending queue, if any. */
+    changesetId?: string;
+    /** Who answered. Absent on answers recorded before identity was tracked. */
+    author?: Author;
+}
+/**
+ * What someone should be able to expect, stated outside the prose.
+ *
+ * A Term says what something *is*; an Expectation says what *happens* in a specific case.
+ * Both are normative, and keeping them apart buys three things the prose cannot:
+ *
+ * - Expectations accumulate. Using the app turns up scenarios nobody thought of the first
+ *   time, and adding one must not mean rewriting a definition that was already correct.
+ * - They are addressable. An id is what lets a test name cite one, a QA agent resolve one,
+ *   and a review notice two that say the same thing.
+ * - They are countable against the vocabulary, which is what makes coverage computable —
+ *   see `coverage.ts`.
+ *
+ * Deliberately *not* a Term. A Term is roughly a class, a thing the product has; an
+ * Expectation is a statement about the vocabulary rather than part of it. Making it a
+ * `TermType` would hand it a parent, attributes, a slot in the glossary browser beside Task,
+ * and a demand for an `implements:` marker — none of which mean anything here. It sits in the
+ * same tier as Question and Changeset: first-class, references terms, is not one.
+ */
+export type ExpectationKind = 'functional' | 'non-functional';
+export type ClashKind = 
+/** Names a term the glossary does not have. */
+'unknown-term'
+/** Says what a live expectation already says. */
+ | 'duplicate'
+/** Concerns exactly the same terms as a live one, in different words. */
+ | 'overlaps'
+/** Cannot hold at the same time as a term's spec. */
+ | 'contradicts'
+/** Restates a spec without adding a scenario. */
+ | 'restates';
+/** Something a draft clashed with, quoted rather than described so both can be read together. */
+export interface Clash {
+    kind: ClashKind;
+    /** The term name or expectation id this is about. */
+    subject: string;
+    detail: string;
+    quote?: string;
+}
+export interface Expectation {
+    id: string;
+    /**
+     * Which verifier this is for, and that is the whole reason the field exists rather than
+     * taxonomy for its own sake. A functional expectation is phrased in glossary vocabulary and
+     * becomes a unit test over the domain. A non-functional one — latency, accessibility,
+     * persistence — is a property of an implementation, which this glossary deliberately does
+     * not constrain, so it is exempt from the vocabulary rule and is checked by driving a
+     * running build instead.
+     *
+     * It is stored rather than derived: emptiness of `terms` looked like it would encode this,
+     * but "listing Tasks in a Project holding ten thousand Tasks stays responsive" is
+     * non-functional and names two terms.
+     */
+    kind: ExpectationKind;
+    /** Who raised it. Absent on expectations raised before identity was tracked. */
+    author?: Author;
+    /**
+     * Draft or published. Absent means `ready`. A draft counts toward nothing — not coverage,
+     * not the versioned contract, and the agents do not see it — until it is published.
+     */
+    status?: RecordStatus;
+    /** Store revision, bumped on every write; the basis for optimistic concurrency. Absent means 1. */
+    rev?: number;
+    /** Glossary terms this concerns. May be empty for a non-functional expectation that scopes to the whole app. */
+    terms: string[];
+    /** The situation. Empty when the expectation is unconditional. */
+    given: string;
+    /** What must hold. For a functional expectation, phrased using only glossary vocabulary. */
+    expect: string;
+    raisedBy: ExpectationOrigin;
+    /**
+     * Id of the expectation that replaced this one, or null while it is live.
+     *
+     * Expectations move — a decision changes, or the first phrasing was imprecise — and an
+     * edit in place would lose both the old wording and the reason. So they are superseded
+     * rather than rewritten, the same way an answer stays in its question file and a changeset
+     * moves to `applied/` instead of vanishing. Three things fall out: a test named `e-014`
+     * still resolves years later, the reasoning is not re-derived, and the one dangerous
+     * direction — quietly weakening an expectation to turn a red check green — leaves an
+     * artifact in the history that is already reviewed.
+     */
+    supersededBy: string | null;
+    /**
+     * Why it stopped applying. Written when it is retired, absent while it is live — the one
+     * field that only ever appears on a retired copy, because a live expectation has no such
+     * reason to record.
+     */
+    retiredBecause?: string;
+    /**
+     * What this clashed with, and was written down anyway.
+     *
+     * The check that finds these does not refuse the write, deliberately: a draft that
+     * contradicts a spec is often a legitimate thing to want that the glossary does not allow
+     * yet, and a model deciding what you may expect from your own product is the wrong
+     * authority. But a finding that lives only in the browser for the second before you click
+     * is worse than no finding — the expectation then lands looking exactly like one that came
+     * back clean, and nothing downstream can tell the difference.
+     *
+     * So the disagreement travels with the statement. An implementer reading this knows not to
+     * go and make it true, because the glossary currently says otherwise and only a human can
+     * settle which gives. Empty means it was checked and clean, or predates the check.
+     */
+    contested: Clash[];
+}
+export interface ExpectationOrigin {
+    /** What was being done when it came up, e.g. `implementation`, `usage`, `review`. */
+    pass: string;
+    /** Question or changeset it follows from, if any. */
+    from?: string;
+    file?: string;
+}
+export type Severity = 'error' | 'warning';
+export interface Diagnostic {
+    /** Index into the op list this diagnostic belongs to, or null when it describes the resulting state as a whole. */
+    opIndex: number | null;
+    severity: Severity;
+    message: string;
+}
+/** A term file that could not be read or did not match the schema. Surfaced in the UI instead of crashing. */
+export interface SourceProblem {
+    file: string;
+    message: string;
+}

package/dist/types.js

@@ -0,0 +1,11 @@
+/**
+ * The glossary schema. These types are the contract between the human authoring
+ * specs in the UI and the AI agent that implements them — everything else in this
+ * repo is a view over data shaped like this.
+ */
+export const TERM_TYPES = [
+    'entity',
+    'event',
+    'function',
+    'attribute-type',
+];

package/dist/valueType.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Attribute value types are a tiny string grammar rather than a nested object, so
+ * the JSON stays hand-editable:
+ *
+ *   string | number | boolean | date | ref:<TermName>     (each with an optional `[]` suffix)
+ */
+export declare const PRIMITIVES: readonly ["string", "number", "boolean", "date"];
+export type Primitive = (typeof PRIMITIVES)[number];
+export type ParsedValueType = {
+    kind: 'primitive';
+    name: Primitive;
+    array: boolean;
+} | {
+    kind: 'ref';
+    name: string;
+    array: boolean;
+};
+export declare function parseValueType(raw: string): ParsedValueType | null;
+export declare function isValueType(raw: string): boolean;
+/** The referenced Term name, or null when the value type is a primitive or unparseable. */
+export declare function refName(raw: string): string | null;
+export declare function formatValueType(parsed: ParsedValueType): string;
+export declare function describeValueTypeError(raw: string): string;

package/dist/valueType.js

@@ -0,0 +1,41 @@
+/**
+ * Attribute value types are a tiny string grammar rather than a nested object, so
+ * the JSON stays hand-editable:
+ *
+ *   string | number | boolean | date | ref:<TermName>     (each with an optional `[]` suffix)
+ */
+export const PRIMITIVES = ['string', 'number', 'boolean', 'date'];
+const VALUE_TYPE = /^(ref:)?([A-Za-z_][A-Za-z0-9_]*)(\[\])?$/;
+export function parseValueType(raw) {
+    const match = VALUE_TYPE.exec(raw.trim());
+    if (!match)
+        return null;
+    const [, refPrefix, name, arraySuffix] = match;
+    const array = arraySuffix === '[]';
+    if (refPrefix)
+        return { kind: 'ref', name: name, array };
+    if (PRIMITIVES.includes(name)) {
+        return { kind: 'primitive', name: name, array };
+    }
+    // A bare capitalised word is almost certainly a Term reference missing its prefix.
+    return null;
+}
+export function isValueType(raw) {
+    return parseValueType(raw) !== null;
+}
+/** The referenced Term name, or null when the value type is a primitive or unparseable. */
+export function refName(raw) {
+    const parsed = parseValueType(raw);
+    return parsed?.kind === 'ref' ? parsed.name : null;
+}
+export function formatValueType(parsed) {
+    const prefix = parsed.kind === 'ref' ? 'ref:' : '';
+    return `${prefix}${parsed.name}${parsed.array ? '[]' : ''}`;
+}
+export function describeValueTypeError(raw) {
+    const bare = raw.trim().replace(/\[\]$/, '');
+    if (/^[A-Z]/.test(bare)) {
+        return `"${raw}" looks like a Term reference — did you mean "ref:${raw}"?`;
+    }
+    return `"${raw}" is not a valid value type (expected ${PRIMITIVES.join(', ')} or ref:<TermName>, with an optional [] suffix)`;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@abseed/spectra-core",
+  "version": "0.1.0",
+  "description": "The Spectra engine: glossary types, the changeset grammar, and the storage seams.",
+  "license": "Apache-2.0",
+  "author": "Luke Pezet",
+  "homepage": "https://github.com/lpezet/spectra/tree/main/packages/core",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lpezet/spectra.git",
+    "directory": "packages/core"
+  },
+  "keywords": [
+    "spectra",
+    "spec-driven",
+    "glossary",
+    "changeset"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "zod": "^3.24.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}