@agentxm/specification-metadata 0.28.14-preview.1789139351.5cd4595aa

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2025-2026 AgentXM, Inc.
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,18 @@
+# @agentxm/specification-metadata
+
+The executable-specification metadata contract that AXM repositories share:
+`defineSpecification`, `defineProductGoals`, `defineExecutionBinding`, and
+`defineBoundEvidence` with their vocabularies (classes, roles, boundaries,
+methods, quality characteristics), the schema decoders that tooling uses to
+read authored metadata, the corpus conformance check, and the shared product
+goal registry. Root export only.
+
+This is engineering support, not runtime code: it ships in the AXM release
+cohort so consumer repositories can author specifications against the same
+contract, but no runtime package may depend on it (ESLint keeps `role:tooling`
+out of every runtime role). Dependency budget: `effect` only. It keeps a local
+copy of the schema-issue formatter rather than depending on the extension
+model, because specifications inside the extension model import this package
+and a model dependency would make the two builds circular.
+
+FSL-1.1-MIT © 2025-2026 AgentXM, Inc.

package/dist/src/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/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/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

package/dist/src/contract.js

@@ -0,0 +1,114 @@
+/**
+ * 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.
+ */
+export const SPECIFICATION_CLASSES = [
+    "functional",
+    "quality",
+    "constraint",
+    "external-conformance",
+    "human-factors",
+    "process",
+];
+export const SPECIFICATION_ROLES = [
+    "experience",
+    "interface",
+    "supporting",
+];
+export const EXECUTION_BOUNDARIES = [
+    "memory",
+    "process",
+    "binary",
+    "packed-artifact",
+    "installed",
+    "platform",
+    "published-artifact",
+    "deployed",
+    "repository",
+];
+export const EXECUTION_SELECTIONS = [
+    "per-change",
+    "platform-matrix",
+    "scheduled",
+    "release-candidate",
+    "post-deployment",
+];
+/**
+ * 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 const KNOWN_SPECIFICATION_METHODS = [
+    "example",
+    "decision-table",
+    "property",
+    "model",
+    "contract",
+    "conformance-matrix",
+    "golden-output",
+    "measurement",
+    "static",
+    "smoke",
+    "manual",
+    "review",
+];
+/**
+ * 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 const UNVERIFIABLE_SPECIFICATION_METHODS = [
+    "manual",
+    "review",
+];
+/**
+ * Known quality characteristics. Required for `quality`-class specifications
+ * and permitted elsewhere; extensible under the same identifier rule as
+ * methods.
+ */
+export const KNOWN_QUALITY_CHARACTERISTICS = [
+    "installability",
+    "compatibility",
+    "performance",
+    "security",
+    "privacy",
+    "reliability",
+    "availability",
+    "maintainability",
+    "observability",
+    "accessibility",
+    "usability",
+];
+/** Segments of a requirement identity or product-goal identity. */
+export const IDENTITY_SEGMENT_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/**
+ * Declares one specification's metadata. Identity function: it exists to type
+ * the literal and to give discovery a stable syntactic anchor.
+ */
+export const defineSpecification = (metadata) => metadata;
+/**
+ * Declares a product-goal registry. Identity function with the same
+ * literal-only discipline as `defineSpecification`.
+ */
+export const defineProductGoals = (registry) => registry;
+/** Declares a boundary-specific execution binding. Identity function. */
+export const defineExecutionBinding = (binding) => binding;
+/**
+ * Declares the static gates bound to a specification as evidence. Exported
+ * as `boundEvidence` beside the `specification` constant. Identity function.
+ */
+export const defineBoundEvidence = (evidence) => evidence;
+//# sourceMappingURL=contract.js.map

package/dist/src/decode.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Decoders for the shared specification contract.
+ *
+ * Catalog tooling extracts each literal statically; result adapters read the
+ * exported constant at run time. Both decode the unknown value through these
+ * schemas so every corpus applies one vocabulary with one set of messages.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+import { type ExecutionBinding, type ProductGoalRegistry, type BoundEvidenceGate, type SpecificationMetadata } from "./contract.js";
+export declare const SpecificationMetadataSchema: Schema.Struct<{
+    readonly requirement: Schema.String;
+    readonly title: Schema.NonEmptyString;
+    readonly statement: Schema.NonEmptyString;
+    readonly class: Schema.Literals<import("./contract.js").SpecificationClass[]>;
+    readonly characteristic: Schema.optionalKey<Schema.String>;
+    readonly role: Schema.Literals<import("./contract.js").SpecificationRole[]>;
+    readonly goals: Schema.NonEmptyArray<Schema.String>;
+    readonly boundary: Schema.optionalKey<Schema.Literals<import("./contract.js").ExecutionBoundary[]>>;
+    readonly boundaryRationale: Schema.optionalKey<Schema.NonEmptyString>;
+    readonly methods: Schema.NonEmptyArray<Schema.String>;
+    readonly selection: Schema.optionalKey<Schema.Literals<import("./contract.js").ExecutionSelection[]>>;
+    readonly derivedFrom: Schema.$Array<Schema.NonEmptyString>;
+    readonly supersedes: Schema.$Array<Schema.NonEmptyString>;
+    readonly assumptions: Schema.Union<readonly [Schema.$Array<Schema.NonEmptyString>, Schema.Literal<"unknown">]>;
+    readonly openQuestions: Schema.Union<readonly [Schema.$Array<Schema.NonEmptyString>, Schema.Literal<"unknown">]>;
+    readonly limitations: Schema.optionalKey<Schema.NonEmptyArray<Schema.Struct<{
+        readonly limitation: Schema.NonEmptyString;
+        readonly retirementCondition: Schema.NonEmptyString;
+    }>>>;
+}>;
+export declare const ProductGoalRegistrySchema: Schema.$Record<Schema.String, Schema.Struct<{
+    readonly outcome: Schema.NonEmptyString;
+    readonly status: Schema.optionalKey<Schema.Literals<readonly ["active", "retired"]>>;
+}>>;
+export declare const ExecutionBindingSchema: Schema.Struct<{
+    readonly requirements: Schema.NonEmptyArray<Schema.String>;
+    readonly boundary: Schema.Literals<import("./contract.js").ExecutionBoundary[]>;
+    readonly rationale: Schema.NonEmptyString;
+}>;
+export declare const BoundEvidenceSchema: Schema.NonEmptyArray<Schema.Struct<{
+    readonly gate: Schema.NonEmptyString;
+    readonly verifies: Schema.NonEmptyString;
+}>>;
+export type DecodeResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly issues: readonly string[];
+};
+export declare const decodeSpecificationMetadata: (value: unknown) => DecodeResult<SpecificationMetadata>;
+export declare const decodeProductGoalRegistry: (value: unknown) => DecodeResult<ProductGoalRegistry>;
+export declare const decodeExecutionBinding: (value: unknown) => DecodeResult<ExecutionBinding>;
+export declare const decodeBoundEvidence: (value: unknown) => DecodeResult<readonly [BoundEvidenceGate, ...BoundEvidenceGate[]]>;
+//# sourceMappingURL=decode.d.ts.map

package/dist/src/decode.js

@@ -0,0 +1,91 @@
+/**
+ * Decoders for the shared specification contract.
+ *
+ * Catalog tooling extracts each literal statically; result adapters read the
+ * exported constant at run time. Both decode the unknown value through these
+ * schemas so every corpus applies one vocabulary with one set of messages.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { formatSchemaIssuesToLines } from "./schema-issues.js";
+import { EXECUTION_BOUNDARIES, EXECUTION_SELECTIONS, IDENTITY_SEGMENT_PATTERN, SPECIFICATION_CLASSES, SPECIFICATION_ROLES, } from "./contract.js";
+const REQUIREMENT_IDENTITY_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*(\/[a-z0-9]+(-[a-z0-9]+)*)+$/;
+const RequirementIdentitySchema = Schema.String.pipe(Schema.check(Schema.isPattern(REQUIREMENT_IDENTITY_PATTERN, {
+    title: "Requirement identity",
+    message: "Expected two or more lowercase kebab segments joined by '/'",
+})));
+const IdentifierSchema = Schema.String.pipe(Schema.check(Schema.isPattern(IDENTITY_SEGMENT_PATTERN, {
+    title: "Identifier",
+    message: "Expected a lowercase kebab identifier",
+})));
+const SpecificationLimitationSchema = Schema.Struct({
+    limitation: Schema.NonEmptyString,
+    retirementCondition: Schema.NonEmptyString,
+});
+const StatedOrUnknownSchema = Schema.Union([
+    Schema.Array(Schema.NonEmptyString),
+    Schema.Literal("unknown"),
+]);
+const specificationClasses = SPECIFICATION_CLASSES.map((entry) => entry);
+const specificationRoles = SPECIFICATION_ROLES.map((entry) => entry);
+const executionBoundaries = EXECUTION_BOUNDARIES.map((entry) => entry);
+const executionSelections = EXECUTION_SELECTIONS.map((entry) => entry);
+export const SpecificationMetadataSchema = Schema.Struct({
+    requirement: RequirementIdentitySchema,
+    title: Schema.NonEmptyString,
+    statement: Schema.NonEmptyString,
+    class: Schema.Literals(specificationClasses),
+    characteristic: Schema.optionalKey(IdentifierSchema),
+    role: Schema.Literals(specificationRoles),
+    goals: Schema.NonEmptyArray(IdentifierSchema),
+    boundary: Schema.optionalKey(Schema.Literals(executionBoundaries)),
+    boundaryRationale: Schema.optionalKey(Schema.NonEmptyString),
+    methods: Schema.NonEmptyArray(IdentifierSchema),
+    selection: Schema.optionalKey(Schema.Literals(executionSelections)),
+    derivedFrom: Schema.Array(Schema.NonEmptyString),
+    supersedes: Schema.Array(Schema.NonEmptyString),
+    assumptions: StatedOrUnknownSchema,
+    openQuestions: StatedOrUnknownSchema,
+    limitations: Schema.optionalKey(Schema.NonEmptyArray(SpecificationLimitationSchema)),
+}).pipe(Schema.check(Schema.makeFilter((metadata) => metadata.class === "quality" && metadata.characteristic === undefined
+    ? "A quality specification must name the characteristic it measures"
+    : undefined), Schema.makeFilter((metadata) => (metadata.boundary ?? "memory") !== "memory" && metadata.boundaryRationale === undefined
+    ? "A specification observed outside memory must state the evidence that boundary supplies"
+    : undefined), Schema.makeFilter((metadata) => metadata.supersedes.some((entry) => metadata.supersedes.indexOf(entry) !== metadata.supersedes.lastIndexOf(entry))
+    ? "supersedes must not repeat an identity"
+    : undefined)));
+const ProductGoalDefinitionSchema = Schema.Struct({
+    outcome: Schema.NonEmptyString,
+    status: Schema.optionalKey(Schema.Literals(["active", "retired"])),
+});
+export const ProductGoalRegistrySchema = Schema.Record(IdentifierSchema, ProductGoalDefinitionSchema);
+export const ExecutionBindingSchema = Schema.Struct({
+    requirements: Schema.NonEmptyArray(RequirementIdentitySchema),
+    boundary: Schema.Literals(executionBoundaries),
+    rationale: Schema.NonEmptyString,
+});
+const BoundEvidenceGateSchema = Schema.Struct({
+    gate: Schema.NonEmptyString,
+    verifies: Schema.NonEmptyString,
+});
+export const BoundEvidenceSchema = Schema.NonEmptyArray(BoundEvidenceGateSchema);
+const toDecodeResult = (result) => Result.isSuccess(result)
+    ? { ok: true, value: result.success }
+    : { ok: false, issues: formatSchemaIssuesToLines(result.failure.issue) };
+/**
+ * Metadata is a closed literal: a field the contract does not define is a
+ * decoding failure, never ignored.
+ */
+const decodeMetadata = Schema.decodeUnknownResult(SpecificationMetadataSchema, {
+    onExcessProperty: "error",
+});
+const decodeRegistry = Schema.decodeUnknownResult(ProductGoalRegistrySchema);
+const decodeBinding = Schema.decodeUnknownResult(ExecutionBindingSchema);
+const decodeEvidence = Schema.decodeUnknownResult(BoundEvidenceSchema);
+export const decodeSpecificationMetadata = (value) => toDecodeResult(decodeMetadata(value));
+export const decodeProductGoalRegistry = (value) => toDecodeResult(decodeRegistry(value));
+export const decodeExecutionBinding = (value) => toDecodeResult(decodeBinding(value));
+export const decodeBoundEvidence = (value) => toDecodeResult(decodeEvidence(value));
+//# sourceMappingURL=decode.js.map

package/dist/src/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Area barrel for the shared executable-specification contract.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export { type BoundEvidenceGate, EXECUTION_BOUNDARIES, EXECUTION_SELECTIONS, type ExecutionBinding, type ExecutionBoundary, type ExecutionSelection, IDENTITY_SEGMENT_PATTERN, KNOWN_QUALITY_CHARACTERISTICS, KNOWN_SPECIFICATION_METHODS, type KnownQualityCharacteristic, type KnownSpecificationMethod, type ProductGoalDefinition, type ProductGoalRegistry, SPECIFICATION_CLASSES, SPECIFICATION_ROLES, type SpecificationClass, type SpecificationLimitation, type SpecificationMetadata, type SpecificationRole, UNVERIFIABLE_SPECIFICATION_METHODS, defineBoundEvidence, defineExecutionBinding, defineProductGoals, defineSpecification, } from "./contract.js";
+export { BoundEvidenceSchema, ExecutionBindingSchema, ProductGoalRegistrySchema, SpecificationMetadataSchema, decodeBoundEvidence, decodeExecutionBinding, decodeProductGoalRegistry, decodeSpecificationMetadata, type DecodeResult, } from "./decode.js";
+export { type ConformanceIssue, type CorpusExecutionBinding, type CorpusInput, type CorpusSpecification, checkSpecificationCorpus, isExecutableMethodSet, lintProductLanguage, } from "./conformance.js";
+export { type SharedProductGoalId, sharedProductGoals } from "./shared-goals.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.js

@@ -0,0 +1,10 @@
+/**
+ * Area barrel for the shared executable-specification contract.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export { EXECUTION_BOUNDARIES, EXECUTION_SELECTIONS, IDENTITY_SEGMENT_PATTERN, KNOWN_QUALITY_CHARACTERISTICS, KNOWN_SPECIFICATION_METHODS, SPECIFICATION_CLASSES, SPECIFICATION_ROLES, UNVERIFIABLE_SPECIFICATION_METHODS, defineBoundEvidence, defineExecutionBinding, defineProductGoals, defineSpecification, } from "./contract.js";
+export { BoundEvidenceSchema, ExecutionBindingSchema, ProductGoalRegistrySchema, SpecificationMetadataSchema, decodeBoundEvidence, decodeExecutionBinding, decodeProductGoalRegistry, decodeSpecificationMetadata, } from "./decode.js";
+export { checkSpecificationCorpus, isExecutableMethodSet, lintProductLanguage, } from "./conformance.js";
+export { sharedProductGoals } from "./shared-goals.js";
+//# sourceMappingURL=index.js.map

package/dist/src/schema-issues.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Schema issue formatting for decode results.
+ *
+ * Deliberately a local copy of the extension model's formatter: this tooling
+ * package is imported by specifications inside the extension model itself,
+ * so a dependency on the model would make the two projects' builds circular.
+ */
+import * as SchemaIssue from "effect/SchemaIssue";
+/**
+ * Format a schema validation issue into human-readable lines with
+ * dot-notation paths, capped at `maxIssues` lines.
+ */
+export declare const formatSchemaIssuesToLines: (issue: SchemaIssue.Issue, maxIssues?: number) => ReadonlyArray<string>;
+//# sourceMappingURL=schema-issues.d.ts.map

package/dist/src/schema-issues.js

@@ -0,0 +1,35 @@
+/**
+ * Schema issue formatting for decode results.
+ *
+ * Deliberately a local copy of the extension model's formatter: this tooling
+ * package is imported by specifications inside the extension model itself,
+ * so a dependency on the model would make the two projects' builds circular.
+ */
+import * as SchemaIssue from "effect/SchemaIssue";
+const DEFAULT_MAX_ISSUES = 5;
+/**
+ * Format a schema validation issue into human-readable lines with
+ * dot-notation paths, capped at `maxIssues` lines.
+ */
+export const formatSchemaIssuesToLines = (issue, maxIssues = DEFAULT_MAX_ISSUES) => {
+    const formatter = SchemaIssue.makeFormatterStandardSchemaV1();
+    const { issues } = formatter(issue);
+    const lines = [];
+    for (const item of issues) {
+        const path = item.path;
+        if (path !== undefined && path.length > 0) {
+            const segments = path.map((segment) => {
+                if (typeof segment === "object" && segment !== null && "key" in segment) {
+                    return String(segment.key);
+                }
+                return String(segment);
+            });
+            lines.push(`${segments.join(".")}: ${item.message}`);
+        }
+        else {
+            lines.push(item.message);
+        }
+    }
+    return lines.slice(0, maxIssues);
+};
+//# sourceMappingURL=schema-issues.js.map

package/dist/src/shared-goals.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared product goals: outcomes that more than one AgentXM repository
+ * serves. Each is registered once, here, with a stable identity; every
+ * repository's specification corpus references these identities and keeps
+ * repository-specific goals in its own local registry. A local registry must
+ * not redefine a shared identity.
+ *
+ * The registry does not restate, own, or rank the specifications that
+ * support a goal. Requirements review walks goals: a retired goal makes its
+ * referencing specifications retirement candidates, and an active goal with
+ * no referencing specification identifies missing coverage or a dead goal.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const sharedProductGoals: {
+    readonly "extension-adoption": {
+        readonly outcome: "People and agents can find, install, update, and remove reusable extensions across coding agents through dependable product surfaces.";
+    };
+    readonly "trustworthy-distribution": {
+        readonly outcome: "Publishing and acquiring extensions preserves integrity, provenance, and immutable accepted resolutions.";
+    };
+    readonly "machine-automation": {
+        readonly outcome: "Machine consumers can drive AgentXM surfaces non-interactively with complete, schema-backed results separated from diagnostics.";
+    };
+    readonly "knowledge-access": {
+        readonly outcome: "People and agents can discover concepts, commands, and contracts from the surface they are already using.";
+    };
+    readonly "privacy-and-consent": {
+        readonly outcome: "Observation of product use stays within the documented data boundary and under the control of the person being observed.";
+    };
+    readonly "dependable-change-process": {
+        readonly outcome: "Changes and releases land through the governed repository process with required evidence and human approval.";
+    };
+};
+export type SharedProductGoalId = keyof typeof sharedProductGoals;
+//# sourceMappingURL=shared-goals.d.ts.map

package/dist/src/shared-goals.js

@@ -0,0 +1,36 @@
+/**
+ * Shared product goals: outcomes that more than one AgentXM repository
+ * serves. Each is registered once, here, with a stable identity; every
+ * repository's specification corpus references these identities and keeps
+ * repository-specific goals in its own local registry. A local registry must
+ * not redefine a shared identity.
+ *
+ * The registry does not restate, own, or rank the specifications that
+ * support a goal. Requirements review walks goals: a retired goal makes its
+ * referencing specifications retirement candidates, and an active goal with
+ * no referencing specification identifies missing coverage or a dead goal.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import { defineProductGoals } from "./contract.js";
+export const sharedProductGoals = defineProductGoals({
+    "extension-adoption": {
+        outcome: "People and agents can find, install, update, and remove reusable extensions across coding agents through dependable product surfaces.",
+    },
+    "trustworthy-distribution": {
+        outcome: "Publishing and acquiring extensions preserves integrity, provenance, and immutable accepted resolutions.",
+    },
+    "machine-automation": {
+        outcome: "Machine consumers can drive AgentXM surfaces non-interactively with complete, schema-backed results separated from diagnostics.",
+    },
+    "knowledge-access": {
+        outcome: "People and agents can discover concepts, commands, and contracts from the surface they are already using.",
+    },
+    "privacy-and-consent": {
+        outcome: "Observation of product use stays within the documented data boundary and under the control of the person being observed.",
+    },
+    "dependable-change-process": {
+        outcome: "Changes and releases land through the governed repository process with required evidence and human approval.",
+    },
+});
+//# sourceMappingURL=shared-goals.js.map

package/package.json

@@ -0,0 +1,47 @@
+{
+  "author": "AgentXM <hello@agentxm.ai> (https://agentxm.ai)",
+  "bugs": {
+    "url": "https://github.com/agentxm/axm/issues"
+  },
+  "dependencies": {
+    "effect": "4.0.0-rc.112"
+  },
+  "description": "Executable-specification metadata contract shared by AXM repositories: specification, product-goal, execution-binding, and bound-evidence definitions, their decoders, and corpus conformance checks. Engineering support, not part of the runtime. Unstable and unsupported.",
+  "devDependencies": {
+    "@effect/vitest": "4.0.0-rc.112",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "exports": {
+    ".": {
+      "axm-source": "./src/index.ts",
+      "default": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/src/",
+    "!**/*.map"
+  ],
+  "homepage": "https://axm.sh",
+  "license": "FSL-1.1-MIT",
+  "name": "@agentxm/specification-metadata",
+  "nx": {
+    "includedScripts": []
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "tools/specification-metadata",
+    "type": "git",
+    "url": "https://github.com/agentxm/axm.git"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "version": "0.28.14-preview.1789139351.5cd4595aa"
+}