@agentxm/extension-model 0.28.4 → 0.28.7-preview.1788522540.63ba4b89a

package/dist/src/unstable/release-channel.d.ts

@@ -0,0 +1,156 @@
+import * as Schema from "effect/Schema";
+/** @experimental This API is unstable and may change without notice. */
+export declare const STABLE_CHANNEL_SCHEMA = "axm.release-channel/v1";
+/** @experimental This API is unstable and may change without notice. */
+export declare const STABLE_CHANNEL_URL = "https://releases.axm.sh/v1/channels/stable.json";
+/** @experimental This API is unstable and may change without notice. */
+export declare const STABLE_CHANNEL_REPOSITORY = "agentxm/axm";
+/**
+ * Public stable-channel document. Exact-version artifacts remain hosted by the
+ * immutable GitHub Release coordinate contained in this validated document.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const StableChannelDocumentV1Schema: Schema.Struct<{
+    readonly schema: Schema.Literal<"axm.release-channel/v1">;
+    readonly channel: Schema.Literal<"stable">;
+    readonly revision: Schema.Int;
+    readonly version: Schema.String;
+    readonly release: Schema.Struct<{
+        readonly repository: Schema.Literal<"agentxm/axm">;
+        readonly tag: Schema.String;
+        readonly commit: Schema.String;
+        readonly publishedAt: Schema.String;
+    }>;
+    readonly artifacts: Schema.Struct<{
+        readonly checksumManifest: Schema.Struct<{
+            readonly name: Schema.Literal<"SHA256SUMS">;
+            readonly url: Schema.String;
+            readonly sha256: Schema.String;
+        }>;
+        readonly binaries: Schema.Tuple<readonly [Schema.Struct<{
+            readonly target: Schema.Literal<"darwin-arm64">;
+            readonly name: Schema.Literal<"axm-darwin-arm64">;
+            readonly url: Schema.String;
+            readonly sha256: Schema.String;
+        }>, Schema.Struct<{
+            readonly target: Schema.Literal<"darwin-x64">;
+            readonly name: Schema.Literal<"axm-darwin-x64">;
+            readonly url: Schema.String;
+            readonly sha256: Schema.String;
+        }>, Schema.Struct<{
+            readonly target: Schema.Literal<"linux-arm64">;
+            readonly name: Schema.Literal<"axm-linux-arm64">;
+            readonly url: Schema.String;
+            readonly sha256: Schema.String;
+        }>, Schema.Struct<{
+            readonly target: Schema.Literal<"linux-x64">;
+            readonly name: Schema.Literal<"axm-linux-x64">;
+            readonly url: Schema.String;
+            readonly sha256: Schema.String;
+        }>, Schema.Struct<{
+            readonly target: Schema.Literal<"windows-x64">;
+            readonly name: Schema.Literal<"axm-windows-x64.exe">;
+            readonly url: Schema.String;
+            readonly sha256: Schema.String;
+        }>]>;
+    }>;
+    readonly promotedAt: Schema.String;
+}>;
+/** @experimental This API is unstable and may change without notice. */
+export type StableChannelDocumentV1 = typeof StableChannelDocumentV1Schema.Type;
+/** @experimental This API is unstable and may change without notice. */
+export declare const decodeStableChannelDocument: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => import("effect/Effect").Effect<{
+    readonly schema: "axm.release-channel/v1";
+    readonly channel: "stable";
+    readonly revision: number;
+    readonly version: string;
+    readonly release: {
+        readonly repository: "agentxm/axm";
+        readonly tag: string;
+        readonly commit: string;
+        readonly publishedAt: string;
+    };
+    readonly artifacts: {
+        readonly checksumManifest: {
+            readonly name: "SHA256SUMS";
+            readonly url: string;
+            readonly sha256: string;
+        };
+        readonly binaries: readonly [{
+            readonly target: "darwin-arm64";
+            readonly name: "axm-darwin-arm64";
+            readonly url: string;
+            readonly sha256: string;
+        }, {
+            readonly target: "darwin-x64";
+            readonly name: "axm-darwin-x64";
+            readonly url: string;
+            readonly sha256: string;
+        }, {
+            readonly target: "linux-arm64";
+            readonly name: "axm-linux-arm64";
+            readonly url: string;
+            readonly sha256: string;
+        }, {
+            readonly target: "linux-x64";
+            readonly name: "axm-linux-x64";
+            readonly url: string;
+            readonly sha256: string;
+        }, {
+            readonly target: "windows-x64";
+            readonly name: "axm-windows-x64.exe";
+            readonly url: string;
+            readonly sha256: string;
+        }];
+    };
+    readonly promotedAt: string;
+}, Schema.SchemaError, never>;
+/** @experimental This API is unstable and may change without notice. */
+export declare const decodeStableChannelDocumentSync: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => {
+    readonly schema: "axm.release-channel/v1";
+    readonly channel: "stable";
+    readonly revision: number;
+    readonly version: string;
+    readonly release: {
+        readonly repository: "agentxm/axm";
+        readonly tag: string;
+        readonly commit: string;
+        readonly publishedAt: string;
+    };
+    readonly artifacts: {
+        readonly checksumManifest: {
+            readonly name: "SHA256SUMS";
+            readonly url: string;
+            readonly sha256: string;
+        };
+        readonly binaries: readonly [{
+            readonly target: "darwin-arm64";
+            readonly name: "axm-darwin-arm64";
+            readonly url: string;
+            readonly sha256: string;
+        }, {
+            readonly target: "darwin-x64";
+            readonly name: "axm-darwin-x64";
+            readonly url: string;
+            readonly sha256: string;
+        }, {
+            readonly target: "linux-arm64";
+            readonly name: "axm-linux-arm64";
+            readonly url: string;
+            readonly sha256: string;
+        }, {
+            readonly target: "linux-x64";
+            readonly name: "axm-linux-x64";
+            readonly url: string;
+            readonly sha256: string;
+        }, {
+            readonly target: "windows-x64";
+            readonly name: "axm-windows-x64.exe";
+            readonly url: string;
+            readonly sha256: string;
+        }];
+    };
+    readonly promotedAt: string;
+};
+//# sourceMappingURL=release-channel.d.ts.map

package/dist/src/unstable/release-channel.js

@@ -0,0 +1,92 @@
+import * as Schema from "effect/Schema";
+import * as semver from "semver";
+/** @experimental This API is unstable and may change without notice. */
+export const STABLE_CHANNEL_SCHEMA = "axm.release-channel/v1";
+/** @experimental This API is unstable and may change without notice. */
+export const STABLE_CHANNEL_URL = "https://releases.axm.sh/v1/channels/stable.json";
+/** @experimental This API is unstable and may change without notice. */
+export const STABLE_CHANNEL_REPOSITORY = "agentxm/axm";
+const Sha256Schema = Schema.String.pipe(Schema.check(Schema.isPattern(/^[0-9a-f]{64}$/u, {
+    message: "Expected a lowercase SHA-256 digest",
+})));
+const UtcInstantSchema = Schema.String.pipe(Schema.check(Schema.makeFilter((value) => {
+    if (!value.endsWith("Z") || Number.isNaN(Date.parse(value))) {
+        return "Expected a valid UTC RFC 3339 instant";
+    }
+    return undefined;
+})));
+const StableVersionSchema = Schema.String.pipe(Schema.check(Schema.makeFilter((value) => {
+    const normalized = semver.valid(value);
+    return normalized === value && semver.prerelease(value) === null
+        ? undefined
+        : "Expected a normalized stable semantic version without a leading v";
+})));
+const ReleaseBinarySchema = (target, name) => Schema.Struct({
+    target: Schema.Literal(target),
+    name: Schema.Literal(name),
+    url: Schema.String,
+    sha256: Sha256Schema,
+});
+const StableChannelDocumentShape = Schema.Struct({
+    schema: Schema.Literal(STABLE_CHANNEL_SCHEMA),
+    channel: Schema.Literal("stable"),
+    revision: Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(1, { message: "Expected a positive revision" }))),
+    version: StableVersionSchema,
+    release: Schema.Struct({
+        repository: Schema.Literal(STABLE_CHANNEL_REPOSITORY),
+        tag: Schema.String,
+        commit: Schema.String.pipe(Schema.check(Schema.isPattern(/^[0-9a-f]{40}$/u, {
+            message: "Expected a lowercase 40-character Git object ID",
+        }))),
+        publishedAt: UtcInstantSchema,
+    }),
+    artifacts: Schema.Struct({
+        checksumManifest: Schema.Struct({
+            name: Schema.Literal("SHA256SUMS"),
+            url: Schema.String,
+            sha256: Sha256Schema,
+        }),
+        binaries: Schema.Tuple([
+            ReleaseBinarySchema("darwin-arm64", "axm-darwin-arm64"),
+            ReleaseBinarySchema("darwin-x64", "axm-darwin-x64"),
+            ReleaseBinarySchema("linux-arm64", "axm-linux-arm64"),
+            ReleaseBinarySchema("linux-x64", "axm-linux-x64"),
+            ReleaseBinarySchema("windows-x64", "axm-windows-x64.exe"),
+        ]),
+    }),
+    promotedAt: UtcInstantSchema,
+});
+const expectedAssetUrl = (tag, name) => `https://github.com/${STABLE_CHANNEL_REPOSITORY}/releases/download/${tag}/${name}`;
+const validateStableChannelDocument = (document) => {
+    const issues = [];
+    const expectedTag = `cli-v${document.version}`;
+    if (document.release.tag !== expectedTag) {
+        issues.push(`release.tag must equal ${expectedTag}`);
+    }
+    const checksumUrl = expectedAssetUrl(expectedTag, document.artifacts.checksumManifest.name);
+    if (document.artifacts.checksumManifest.url !== checksumUrl) {
+        issues.push(`artifacts.checksumManifest.url must equal ${checksumUrl}`);
+    }
+    for (const binary of document.artifacts.binaries) {
+        const url = expectedAssetUrl(expectedTag, binary.name);
+        if (binary.url !== url) {
+            issues.push(`artifact URL for ${binary.name} must equal ${url}`);
+        }
+    }
+    if (Date.parse(document.promotedAt) < Date.parse(document.release.publishedAt)) {
+        issues.push("promotedAt must not be earlier than release.publishedAt");
+    }
+    return issues;
+};
+/**
+ * Public stable-channel document. Exact-version artifacts remain hosted by the
+ * immutable GitHub Release coordinate contained in this validated document.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const StableChannelDocumentV1Schema = StableChannelDocumentShape.pipe(Schema.check(Schema.makeFilter(validateStableChannelDocument)));
+/** @experimental This API is unstable and may change without notice. */
+export const decodeStableChannelDocument = Schema.decodeUnknownEffect(StableChannelDocumentV1Schema);
+/** @experimental This API is unstable and may change without notice. */
+export const decodeStableChannelDocumentSync = Schema.decodeUnknownSync(StableChannelDocumentV1Schema);
+//# sourceMappingURL=release-channel.js.map

package/dist/src/unstable/specifications/conformance.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Corpus conformance for executable specifications.
+ *
+ * A pure check over already-decoded metadata: it establishes that a
+ * specification corpus has the contract's form and linkage — vocabulary,
+ * identity, goal references, boundary rationale, lineage, and product
+ * language. A clean result never establishes that the accepted obligations
+ * are the right ones; that judgment stays with set review and the acceptance
+ * decision.
+ *
+ * Both repositories run this check over their own corpus. Shared goal
+ * identities come from the installed contract, so a specification that names
+ * a shared goal the installed release cohort does not register is a dangling
+ * cross-repository reference and fails here.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import { type ExecutionBinding, type ProductGoalRegistry, type SpecificationMetadata } from "./contract.js";
+export interface ConformanceIssue {
+    readonly severity: "error" | "warning";
+    /** Repository-relative source the issue is anchored to. */
+    readonly source: string;
+    readonly message: string;
+}
+export interface CorpusSpecification {
+    /** Repository-relative source path of the specification file. */
+    readonly source: string;
+    readonly metadata: SpecificationMetadata;
+}
+export interface CorpusExecutionBinding {
+    /** Repository-relative source path of the boundary execution. */
+    readonly source: string;
+    readonly binding: ExecutionBinding;
+}
+export interface CorpusInput {
+    readonly specifications: readonly CorpusSpecification[];
+    /** The repository's local product-goal registry. */
+    readonly localGoals: ProductGoalRegistry;
+    /** Source path reported for local-registry issues. */
+    readonly localGoalsSource: string;
+    /** Shared goals from the installed contract. Defaults to `sharedProductGoals`. */
+    readonly sharedGoals?: ProductGoalRegistry;
+    readonly executionBindings?: readonly CorpusExecutionBinding[];
+}
+/**
+ * Whether at least one declared method produces runner evidence. A method
+ * set made only of unverifiable methods is reported as unverified by the
+ * harness, never as passing.
+ */
+export declare const isExecutableMethodSet: (methods: readonly string[]) => boolean;
+/**
+ * Lints a title or statement for implementation vocabulary. Specification
+ * text describes conditions and observable results; it never names
+ * handlers, services, Layers, private functions, or mock interactions.
+ */
+export declare const lintProductLanguage: (text: string) => string | undefined;
+/**
+ * Checks one corpus for contract form and linkage. Issues are ordered by
+ * discovery; callers decide whether warnings block.
+ */
+export declare const checkSpecificationCorpus: (input: CorpusInput) => readonly ConformanceIssue[];
+//# sourceMappingURL=conformance.d.ts.map

package/dist/src/unstable/specifications/conformance.js

@@ -0,0 +1,137 @@
+/**
+ * Corpus conformance for executable specifications.
+ *
+ * A pure check over already-decoded metadata: it establishes that a
+ * specification corpus has the contract's form and linkage — vocabulary,
+ * identity, goal references, boundary rationale, lineage, and product
+ * language. A clean result never establishes that the accepted obligations
+ * are the right ones; that judgment stays with set review and the acceptance
+ * decision.
+ *
+ * Both repositories run this check over their own corpus. Shared goal
+ * identities come from the installed contract, so a specification that names
+ * a shared goal the installed release cohort does not register is a dangling
+ * cross-repository reference and fails here.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import { IDENTITY_SEGMENT_PATTERN, UNVERIFIABLE_SPECIFICATION_METHODS, } from "./contract.js";
+import { sharedProductGoals } from "./shared-goals.js";
+/** Words that identify implementation vocabulary leaking into product language. */
+const IMPLEMENTATION_WORDS = new Set([
+    "layer",
+    "handler",
+    "mock",
+    "stub",
+    "middleware",
+    "refactor",
+]);
+const CAMEL_CASE_TOKEN = /\b[a-z]+[A-Z][A-Za-z]*\b/;
+/**
+ * Whether at least one declared method produces runner evidence. A method
+ * set made only of unverifiable methods is reported as unverified by the
+ * harness, never as passing.
+ */
+export const isExecutableMethodSet = (methods) => methods.some((method) => !UNVERIFIABLE_SPECIFICATION_METHODS.some((entry) => entry === method));
+/**
+ * Lints a title or statement for implementation vocabulary. Specification
+ * text describes conditions and observable results; it never names
+ * handlers, services, Layers, private functions, or mock interactions.
+ */
+export const lintProductLanguage = (text) => {
+    if (CAMEL_CASE_TOKEN.test(text)) {
+        return `contains an implementation-style camelCase token: "${text}"`;
+    }
+    for (const word of text.toLowerCase().split(/[^a-z]+/)) {
+        if (IMPLEMENTATION_WORDS.has(word)) {
+            return `contains implementation vocabulary ("${word}"): "${text}"`;
+        }
+    }
+    return undefined;
+};
+const error = (source, message) => ({
+    severity: "error",
+    source,
+    message,
+});
+const warning = (source, message) => ({
+    severity: "warning",
+    source,
+    message,
+});
+/**
+ * Checks one corpus for contract form and linkage. Issues are ordered by
+ * discovery; callers decide whether warnings block.
+ */
+export const checkSpecificationCorpus = (input) => {
+    const issues = [];
+    const sharedGoals = input.sharedGoals ?? sharedProductGoals;
+    for (const id of Object.keys(input.localGoals)) {
+        if (!IDENTITY_SEGMENT_PATTERN.test(id)) {
+            issues.push(error(input.localGoalsSource, `product-goal id \`${id}\` must be a lowercase kebab identifier`));
+        }
+        if (Object.hasOwn(sharedGoals, id)) {
+            issues.push(error(input.localGoalsSource, `product goal \`${id}\` is a shared goal; reference the shared identity instead of redefining it locally`));
+        }
+    }
+    const registeredGoals = new Map();
+    for (const registry of [sharedGoals, input.localGoals]) {
+        for (const [id, definition] of Object.entries(registry)) {
+            registeredGoals.set(id, { status: definition.status ?? "active" });
+        }
+    }
+    const byRequirement = new Map();
+    for (const specification of input.specifications) {
+        const existing = byRequirement.get(specification.metadata.requirement);
+        if (existing !== undefined) {
+            issues.push(error(specification.source, `duplicate requirement identity \`${specification.metadata.requirement}\` (also declared in ${existing.source})`));
+            continue;
+        }
+        byRequirement.set(specification.metadata.requirement, specification);
+    }
+    const referencedGoals = new Set();
+    for (const { source, metadata } of input.specifications) {
+        for (const goal of metadata.goals) {
+            referencedGoals.add(goal);
+            const registered = registeredGoals.get(goal);
+            if (registered === undefined) {
+                issues.push(error(source, `references unregistered product goal \`${goal}\``));
+            }
+            else if (registered.status === "retired") {
+                issues.push(error(source, `references retired product goal \`${goal}\`; the specification is a retirement candidate`));
+            }
+        }
+        for (const superseded of metadata.supersedes) {
+            if (byRequirement.has(superseded)) {
+                issues.push(error(source, `supersedes \`${superseded}\`, which is still present in the corpus; retire the predecessor in the same change`));
+            }
+        }
+        const titleFinding = lintProductLanguage(metadata.title);
+        if (titleFinding !== undefined) {
+            issues.push(error(source, `title ${titleFinding}`));
+        }
+        const statementFinding = lintProductLanguage(metadata.statement);
+        if (statementFinding !== undefined) {
+            issues.push(error(source, `statement ${statementFinding}`));
+        }
+        if (!isExecutableMethodSet(metadata.methods)) {
+            issues.push(warning(source, `declares only unverifiable methods (${metadata.methods.join(", ")}); the harness reports this specification as unverified`));
+        }
+    }
+    for (const [id, definition] of registeredGoals) {
+        if (definition.status === "active" &&
+            !referencedGoals.has(id) &&
+            input.specifications.length > 0) {
+            issues.push(warning(input.localGoalsSource, `active product goal \`${id}\` has no referencing specification (missing coverage or a dead goal)`));
+        }
+    }
+    for (const { source, binding } of input.executionBindings ?? []) {
+        for (const requirement of binding.requirements) {
+            if (!byRequirement.has(requirement)) {
+                issues.push(error(source, `execution binding references unknown requirement \`${requirement}\``));
+            }
+        }
+    }
+    return issues;
+};
+//# sourceMappingURL=conformance.js.map

package/dist/src/unstable/specifications/contract.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Shared executable-specification contract.
+ *
+ * One metadata contract, one classification lens, one set of controlled
+ * vocabularies, and one shared product-goal registry for every AgentXM
+ * specification corpus. Each repository keeps its own specification files,
+ * local product goals, and local placement rules; only this contract and the
+ * shared goal identities cross the repository boundary.
+ *
+ * Metadata is data. Every specification file exports one `specification`
+ * constant built with `defineSpecification`: a literal object carrying only
+ * the cross-method information that discovery, conformance, and reporting
+ * need. It never wraps or replaces native test-framework constructs, and
+ * catalog tooling reads it statically without executing the specification.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+/**
+ * The review lens a specification is classified by. Classification selects
+ * the review expertise and quality criteria the obligation most needs; it
+ * does not determine priority, acceptance, subject, or verification method.
+ *
+ * - `functional`: responses, transformations, rules, and observable
+ *   capabilities;
+ * - `quality`: a measurable degree such as performance, reliability,
+ *   security, or installability, named by `characteristic`;
+ * - `constraint`: a genuine restriction on solution, environment,
+ *   technology, or operation;
+ * - `external-conformance`: an obligation adopted from a named law,
+ *   standard, contract, or interface;
+ * - `human-factors`: capabilities and qualities arising from people, tasks,
+ *   accessibility, ergonomics, or context of use; and
+ * - `process`: an obligation on development, delivery, operation, support,
+ *   migration, or retirement.
+ */
+export type SpecificationClass = "functional" | "quality" | "constraint" | "external-conformance" | "human-factors" | "process";
+export declare const SPECIFICATION_CLASSES: readonly SpecificationClass[];
+/**
+ * How a specification participates in the product contract and its reading
+ * paths. Experience specifications describe tasks in product language,
+ * interface specifications state public machine-consumable contracts, and
+ * supporting specifications state subordinate system or engineering
+ * obligations.
+ */
+export type SpecificationRole = "experience" | "interface" | "supporting";
+export declare const SPECIFICATION_ROLES: readonly SpecificationRole[];
+/**
+ * Where the specification's default execution observes the system.
+ * Additional boundary-specific executions bind their own evidence to the
+ * same requirement identity.
+ */
+export type ExecutionBoundary = "memory" | "process" | "binary" | "packed-artifact" | "installed" | "platform" | "published-artifact" | "deployed" | "repository";
+export declare const EXECUTION_BOUNDARIES: readonly ExecutionBoundary[];
+/** When this specification's evidence is selected by default. */
+export type ExecutionSelection = "per-change" | "platform-matrix" | "scheduled" | "release-candidate" | "post-deployment";
+export declare const EXECUTION_SELECTIONS: readonly ExecutionSelection[];
+/**
+ * Known testing methods. The vocabulary is extensible: a method not listed
+ * here is accepted when it is a lowercase kebab identifier, so a new or
+ * combined method never needs a contract change before use.
+ */
+export declare const KNOWN_SPECIFICATION_METHODS: readonly ["example", "decision-table", "property", "model", "contract", "conformance-matrix", "golden-output", "measurement", "static", "smoke", "manual", "review"];
+export type KnownSpecificationMethod = (typeof KNOWN_SPECIFICATION_METHODS)[number];
+/**
+ * Methods whose evidence is produced by a person rather than a runner. A
+ * specification whose methods are all unverifiable is reported as unverified
+ * by the harness; it is never reported as passing.
+ */
+export declare const UNVERIFIABLE_SPECIFICATION_METHODS: readonly KnownSpecificationMethod[];
+/**
+ * Known quality characteristics. Required for `quality`-class specifications
+ * and permitted elsewhere; extensible under the same identifier rule as
+ * methods.
+ */
+export declare const KNOWN_QUALITY_CHARACTERISTICS: readonly ["installability", "compatibility", "performance", "security", "privacy", "reliability", "availability", "maintainability", "observability", "accessibility", "usability"];
+export type KnownQualityCharacteristic = (typeof KNOWN_QUALITY_CHARACTERISTICS)[number];
+/** Segments of a requirement identity or product-goal identity. */
+export declare const IDENTITY_SEGMENT_PATTERN: RegExp;
+/** A declared blind spot of one specification and the condition that retires it. */
+export interface SpecificationLimitation {
+    /** What the specification's evidence cannot establish, in product language. */
+    readonly limitation: string;
+    /** The observable condition under which this limitation is removed. */
+    readonly retirementCondition: string;
+}
+export interface SpecificationMetadata {
+    /**
+     * Stable requirement identity: lowercase kebab path segments joined by `/`,
+     * for example `cli/install/realizes-direct-intent`. Declared here, not
+     * derived from the filesystem; repository policy keeps it equal to the
+     * file's path under `specifications/`, so moving or renaming a file is an
+     * identity change — a requirements decision.
+     */
+    readonly requirement: string;
+    /** Product-language title, readable without the source. */
+    readonly title: string;
+    /**
+     * The normative statement: obligated subject, condition or trigger, and
+     * the required or prohibited outcome, in product language. This sentence
+     * is the obligation; native tests are its reportable scenarios.
+     */
+    readonly statement: string;
+    /** The review lens this specification is classified by. */
+    readonly class: SpecificationClass;
+    /**
+     * The quality characteristic a `quality` specification measures, or the
+     * human-factors quality a `human-factors` specification names. Required
+     * for `quality`; optional otherwise.
+     */
+    readonly characteristic?: string;
+    /** The specification's primary role in the product contract. */
+    readonly role: SpecificationRole;
+    /**
+     * Registered product-goal identities this specification supports. Every
+     * entry must exist, active, in the shared registry or the repository's
+     * local registry.
+     */
+    readonly goals: readonly [string, ...string[]];
+    /** Observation boundary of the default execution. Defaults to `memory`. */
+    readonly boundary?: ExecutionBoundary;
+    /**
+     * Why this specification observes a boundary other than memory: the
+     * evidence that boundary supplies which an in-memory run cannot. Required
+     * whenever `boundary` is not `memory`.
+     */
+    readonly boundaryRationale?: string;
+    /** Testing methods the specification actually uses. */
+    readonly methods: readonly [string, ...string[]];
+    /** Default evidence-selection policy. Defaults to `per-change`. */
+    readonly selection?: ExecutionSelection;
+    /**
+     * Sources this obligation was derived from: predecessor requirement
+     * identities, prior specification identities, tests that witnessed the
+     * behavior, or surfaces that supplied its conditions. Empty when the
+     * specification is an original source.
+     */
+    readonly derivedFrom: readonly string[];
+    /**
+     * Identities this specification replaces as authority. A superseded
+     * identity is retired in the same change that lands its successor and
+     * must not remain present in the corpus.
+     */
+    readonly supersedes: readonly string[];
+    /**
+     * Conditions the obligation presumes and its evidence does not establish.
+     * An empty list records that none were found after review; `"unknown"`
+     * records that assumptions have not been assessed.
+     */
+    readonly assumptions: readonly string[] | "unknown";
+    /**
+     * Unresolved questions about the obligation's meaning, scope, or subject.
+     * An empty list records that none remain; `"unknown"` records that the
+     * specification has not been reviewed for open questions.
+     */
+    readonly openQuestions: readonly string[] | "unknown";
+    /** Declared blind spots of this specification's evidence. */
+    readonly limitations?: readonly [SpecificationLimitation, ...SpecificationLimitation[]];
+}
+/**
+ * Declares one specification's metadata. Identity function: it exists to type
+ * the literal and to give discovery a stable syntactic anchor.
+ */
+export declare const defineSpecification: <const M extends SpecificationMetadata>(metadata: M) => M;
+/** One registered product goal. */
+export interface ProductGoalDefinition {
+    /** One-sentence statement of the desired outcome this goal names. */
+    readonly outcome: string;
+    /**
+     * Retired goals stay registered so specifications referencing them are
+     * flagged as retirement candidates instead of silently orphaned.
+     */
+    readonly status?: "active" | "retired";
+}
+export type ProductGoalRegistry = Readonly<Record<string, ProductGoalDefinition>>;
+/**
+ * Declares a product-goal registry. Identity function with the same
+ * literal-only discipline as `defineSpecification`.
+ */
+export declare const defineProductGoals: <const R extends ProductGoalRegistry>(registry: R) => R;
+/**
+ * Binds a boundary-specific execution (for example an end-to-end test file)
+ * to the requirement identities it provides evidence for. The execution is
+ * evidence, never a second authority: it must not state new requirements.
+ */
+export interface ExecutionBinding {
+    /** Requirement identities this execution binds evidence to. */
+    readonly requirements: readonly [string, ...string[]];
+    /** Observation boundary of this execution. */
+    readonly boundary: ExecutionBoundary;
+    /**
+     * The boundary-specific reason this execution exists beyond the in-memory
+     * evidence — required so boundary scenarios never silently duplicate
+     * in-memory scenarios.
+     */
+    readonly rationale: string;
+}
+/** Declares a boundary-specific execution binding. Identity function. */
+export declare const defineExecutionBinding: <const B extends ExecutionBinding>(binding: B) => B;
+/**
+ * One static verification gate whose result is bound to the owning
+ * specification's requirement identity. Bound evidence supports the owning
+ * specification; it never replaces it and never states a new requirement.
+ */
+export interface BoundEvidenceGate {
+    /** The static gate, named by the verification surface that runs it. */
+    readonly gate: string;
+    /** What the gate verifies for this requirement, in product language. */
+    readonly verifies: string;
+}
+/**
+ * Declares the static gates bound to a specification as evidence. Exported
+ * as `boundEvidence` beside the `specification` constant. Identity function.
+ */
+export declare const defineBoundEvidence: <const E extends readonly [BoundEvidenceGate, ...BoundEvidenceGate[]]>(evidence: E) => E;
+//# sourceMappingURL=contract.d.ts.map