@agentxm/extension-model 0.28.4 → 0.28.6

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