@lucern/contracts 1.0.55 → 1.0.57

package/dist/manifests/operation-manifest.js

@@ -0,0 +1,306 @@
+import { z } from 'zod';
+
+// src/manifests/operation-manifest.ts
+var OPERATION_VERBS = [
+  // read plane
+  "get",
+  "list",
+  "search",
+  "traverse",
+  "compile",
+  "diff",
+  "replay",
+  // write plane
+  "create",
+  "refine",
+  "append",
+  "fork",
+  "transition",
+  "evaluate",
+  "graduate",
+  // governance plane
+  "declare",
+  "bind",
+  "grant"
+];
+var OPERATION_KINDS = [
+  "node",
+  "edge",
+  "container",
+  "slice",
+  "record",
+  "policy",
+  "unresolved"
+];
+var OPERATION_AXES = [
+  "scope",
+  "horizon",
+  "lens",
+  "policy",
+  "strategy",
+  "carrier"
+];
+var PROJECTION_CLASSES = [
+  "canonical_public",
+  "internal_backing",
+  "extension",
+  "compat",
+  "client_local"
+];
+var SURFACE_EXPOSURE = ["public", "internal", "absent"];
+var OPERATION_SOURCES = [
+  "registry",
+  "kernelApi",
+  "mcp_extension",
+  "cli_bespoke"
+];
+var operationRowSchema = z.object({
+  /** Canonical operation identity. Snake_case for graph operations; dotted
+   *  `domain.method` for kernelApi host bindings; `domain subcommand` for CLI
+   *  bespoke handlers. Unique across the manifest. */
+  name: z.string().min(1),
+  /** SC.2 verb. */
+  verb: z.enum(OPERATION_VERBS),
+  /** SC.2 target: the kind, and an optional type that narrows it. */
+  target: z.object({
+    kind: z.enum(OPERATION_KINDS),
+    type: z.string().min(1).optional()
+  }),
+  /** SC.2 axes this operation accepts. */
+  axes: z.array(z.enum(OPERATION_AXES)).readonly(),
+  /** Projection class (design doc): where in the surface taxonomy this row
+   *  lives. `internal_backing` is a class, not a second language. */
+  projection: z.object({
+    class: z.enum(PROJECTION_CLASSES),
+    /** Per-surface exposure. `kernelApi` is present so the shadow surface is
+     *  expressible; the four public surfaces mirror the registry map. */
+    surfaces: z.object({
+      sdk: z.enum(SURFACE_EXPOSURE),
+      rest: z.enum(SURFACE_EXPOSURE),
+      mcp: z.enum(SURFACE_EXPOSURE),
+      cli: z.enum(SURFACE_EXPOSURE),
+      host: z.enum(SURFACE_EXPOSURE),
+      kernelApi: z.enum(SURFACE_EXPOSURE)
+    }),
+    /** Compat rows carry an alias + exit-criteria doc pointer. */
+    compat: z.object({ aliasOf: z.string(), exitCriteria: z.string() }).optional()
+  }),
+  /** Where this row was expressed from (census population). */
+  source: z.enum(OPERATION_SOURCES),
+  /** Concrete source binding: the code location this row projects. For registry
+   *  rows, the registry entry name; for kernelApi rows, the `api.*` ref path and
+   *  its `components.lucern.*` component path; for extension/bespoke rows, the
+   *  wiring symbol / command path. */
+  binding: z.object({
+    /** The primary source identifier (registry name, api ref path, tool name,
+     *  or CLI command path). */
+    ref: z.string().min(1),
+    /** kernelApi component path (`components.lucern.*`) when source=kernelApi. */
+    componentPath: z.string().optional(),
+    /** For extension/bespoke rows that back a registry op, the registry op name
+     *  they are a projection of (so census facts about registry ops are
+     *  expressed on the row, not double-counted as phantom operations). */
+    backsRegistryOp: z.string().optional()
+  }),
+  /** Lifecycle status. `active` for served operations; `compat` for legacy
+   *  aliases awaiting deletion criteria. */
+  status: z.enum(["active", "compat"]),
+  /** M2-derivation pointers, named-but-null in M1 (see file header). */
+  derivation: z.object({
+    /** Arg/returns schema derived in M2. Null in M1. */
+    schema: z.null(),
+    /** Legality-matrix row derived in M2. Null in M1. */
+    legality: z.null(),
+    /** Receipt shape derived in M2. Null in M1. */
+    receipt: z.null()
+  }),
+  /** Human-readable provenance from the census/registry. */
+  rationale: z.string()
+});
+var operationManifestSchema = z.object({
+  schemaVersion: z.literal("operation_manifest.m1.v1"),
+  generatedAt: z.string(),
+  /** Census reconciliation block: the counts this manifest expresses, keyed by
+   *  the SC.1 disposition dimensions, so the derivability test can assert them
+   *  against the disposition doc and surface any point-in-time delta. */
+  census: z.object({
+    total: z.number(),
+    bySource: z.object({
+      registry: z.number(),
+      kernelApi: z.number(),
+      mcp_extension: z.number(),
+      cli_bespoke: z.number()
+    }),
+    byProjectionClass: z.object({
+      canonical_public: z.number(),
+      internal_backing: z.number(),
+      extension: z.number(),
+      compat: z.number(),
+      client_local: z.number()
+    }),
+    registryBySurfaceClass: z.record(z.string(), z.number())
+  }),
+  operations: z.array(operationRowSchema)
+});
+var SC1_CENSUS_TARGETS = {
+  /** 190 function-registry contracts (surface-manifest.json). Exact. */
+  registryContracts: 190,
+  /** Registry class split (161 canonical public + 25 internal + 4 compat). */
+  registryCanonicalPublic: 161,
+  registryPlatformInternal: 25,
+  registryLegacyCompat: 4,
+  /** kernelApi allowlist refs. Census recorded 124 post-#1651; the live
+   *  allowlist is the authority and the check tolerates a documented delta. */
+  kernelApiRefsCensus: 124,
+  /** MCP extension wirings the server hand-registers beyond the generated
+   *  build (census: 159 MCP tools − 144 generated = 15). Every extension tool
+   *  is *also* a registry contract, so these are expressed as projection facts
+   *  (mcp_extension source rows that `backsRegistryOp`), not new operations. */
+  mcpExtensions: 15,
+  /** CLI bespoke handlers (census: 19). Gateway-hitting bespoke verbs +
+   *  client-local tooling. Expressed as cli_bespoke rows; the gateway-hitting
+   *  subset backs a registry op or is a promotion candidate. */
+  cliBespoke: 19
+};
+var MCP_EXTENSION_WIRINGS = [
+  // bootstrap group (BOOTSTRAP_MCP_TOOLS)
+  "generate_session_handoff",
+  "begin_build_session",
+  // coordination group (COORDINATION_MCP_TOOLS) — the SC.1 session-runtime family
+  "register_session",
+  "heartbeat_session",
+  "end_session",
+  "list_active_sessions",
+  "send_agent_message",
+  "broadcast_message",
+  "get_agent_inbox",
+  "claim_files",
+  // epistemic-contract group (EPISTEMIC_CONTRACT_MCP_TOOLS)
+  "create_epistemic_contract",
+  "evaluate_contract",
+  "get_contract_status",
+  // MCP-only internal contract evaluators (manifest.ts MCP_ONLY_INTERNAL_OPERATION_NAMES)
+  "evaluate_engineering_contract",
+  "evaluate_research_contract"
+];
+var CLI_BESPOKE_HANDLERS = [
+  // gateway-hitting bespoke verbs (SC.1: the 5 promotion candidates + the
+  // reconciliation/capture verbs that also carry bespoke handlers)
+  {
+    command: "checkpoint",
+    gatewayHitting: true,
+    backsRegistryOp: null,
+    promotionCandidate: true
+  },
+  {
+    command: "evidence record-ci",
+    gatewayHitting: true,
+    backsRegistryOp: "create_evidence",
+    promotionCandidate: true
+  },
+  {
+    command: "dispatch record",
+    gatewayHitting: true,
+    backsRegistryOp: null,
+    promotionCandidate: true
+  },
+  {
+    command: "pivot record",
+    gatewayHitting: true,
+    backsRegistryOp: null,
+    promotionCandidate: true
+  },
+  {
+    command: "contradiction declare",
+    gatewayHitting: true,
+    backsRegistryOp: "flag_contradiction",
+    promotionCandidate: true
+  },
+  {
+    command: "campaign closeout",
+    gatewayHitting: true,
+    backsRegistryOp: null,
+    promotionCandidate: false
+  },
+  {
+    command: "worktrees context",
+    gatewayHitting: true,
+    backsRegistryOp: "get_worktree",
+    promotionCandidate: false
+  },
+  {
+    command: "worktrees reconcile-gate",
+    gatewayHitting: true,
+    backsRegistryOp: null,
+    promotionCandidate: false
+  },
+  {
+    command: "embeddings",
+    gatewayHitting: true,
+    backsRegistryOp: null,
+    promotionCandidate: false
+  },
+  // client-local handlers (SC.1 §"Client-local ~10") — no server operation
+  {
+    command: "auth",
+    gatewayHitting: false,
+    backsRegistryOp: null,
+    promotionCandidate: false
+  },
+  {
+    command: "profile",
+    gatewayHitting: false,
+    backsRegistryOp: null,
+    promotionCandidate: false
+  },
+  {
+    command: "scope",
+    gatewayHitting: false,
+    backsRegistryOp: null,
+    promotionCandidate: false
+  },
+  {
+    command: "doctor",
+    gatewayHitting: false,
+    backsRegistryOp: null,
+    promotionCandidate: false
+  },
+  {
+    command: "completions",
+    gatewayHitting: false,
+    backsRegistryOp: null,
+    promotionCandidate: false
+  },
+  {
+    command: "login",
+    gatewayHitting: false,
+    backsRegistryOp: null,
+    promotionCandidate: false
+  },
+  {
+    command: "version",
+    gatewayHitting: false,
+    backsRegistryOp: null,
+    promotionCandidate: false
+  },
+  {
+    command: "functions",
+    gatewayHitting: false,
+    backsRegistryOp: null,
+    promotionCandidate: false
+  },
+  {
+    command: "replay",
+    gatewayHitting: false,
+    backsRegistryOp: null,
+    promotionCandidate: false
+  },
+  {
+    command: "local-workflow",
+    gatewayHitting: false,
+    backsRegistryOp: null,
+    promotionCandidate: false
+  }
+];
+
+export { CLI_BESPOKE_HANDLERS, MCP_EXTENSION_WIRINGS, OPERATION_AXES, OPERATION_KINDS, OPERATION_SOURCES, OPERATION_VERBS, PROJECTION_CLASSES, SC1_CENSUS_TARGETS, SURFACE_EXPOSURE, operationManifestSchema, operationRowSchema };

package/dist/projections/check-convex-args-shape.js

@@ -6043,6 +6043,14 @@ DATA_MODEL_MANIFEST_SKELETON.surfaces.map(
   (surface) => surface.compositionEmitted
 );
 var EVIDENCE_RELATION_VALUES = ["supports", "contradicts"];
+var EVIDENCE_KIND_VALUES = [
+  "fact",
+  "observation",
+  "claim",
+  "quote",
+  "statistic",
+  "signal"
+];
 var EVIDENCE_METHODOLOGY_VALUES = [
   "primary_research",
   "expert_interview",
@@ -6096,6 +6104,7 @@ var EVIDENCE_TAXONOMY_REFUSAL_IDS = [
   "metadata_scoring_plan_refused"
 ];
 z.enum(EVIDENCE_RELATION_VALUES);
+z.enum(EVIDENCE_KIND_VALUES);
 z.enum(EVIDENCE_METHODOLOGY_VALUES);
 z.enum(
   EVIDENCE_INFORMATION_ASYMMETRY_VALUES

package/dist/projections/create-evidence.projection.js

@@ -5900,6 +5900,14 @@ DATA_MODEL_MANIFEST_SKELETON.surfaces.map(
   (surface) => surface.compositionEmitted
 );
 var EVIDENCE_RELATION_VALUES = ["supports", "contradicts"];
+var EVIDENCE_KIND_VALUES = [
+  "fact",
+  "observation",
+  "claim",
+  "quote",
+  "statistic",
+  "signal"
+];
 var EVIDENCE_METHODOLOGY_VALUES = [
   "primary_research",
   "expert_interview",
@@ -5953,6 +5961,7 @@ var EVIDENCE_TAXONOMY_REFUSAL_IDS = [
   "metadata_scoring_plan_refused"
 ];
 z.enum(EVIDENCE_RELATION_VALUES);
+z.enum(EVIDENCE_KIND_VALUES);
 z.enum(EVIDENCE_METHODOLOGY_VALUES);
 z.enum(
   EVIDENCE_INFORMATION_ASYMMETRY_VALUES

package/dist/projections/index.js

@@ -6043,6 +6043,14 @@ DATA_MODEL_MANIFEST_SKELETON.surfaces.map(
   (surface) => surface.compositionEmitted
 );
 var EVIDENCE_RELATION_VALUES = ["supports", "contradicts"];
+var EVIDENCE_KIND_VALUES = [
+  "fact",
+  "observation",
+  "claim",
+  "quote",
+  "statistic",
+  "signal"
+];
 var EVIDENCE_METHODOLOGY_VALUES = [
   "primary_research",
   "expert_interview",
@@ -6096,6 +6104,7 @@ var EVIDENCE_TAXONOMY_REFUSAL_IDS = [
   "metadata_scoring_plan_refused"
 ];
 z.enum(EVIDENCE_RELATION_VALUES);
+z.enum(EVIDENCE_KIND_VALUES);
 z.enum(EVIDENCE_METHODOLOGY_VALUES);
 z.enum(
   EVIDENCE_INFORMATION_ASYMMETRY_VALUES

package/dist/proof-attestation.json

@@ -41,5 +41,5 @@
     "convex-validators",
     "proof-attestation"
   ],
-  "signedAt": 1782826831970
+  "signedAt": 1783073301464
 }

package/dist/schema-helpers/evidenceAdmission.d.ts

@@ -0,0 +1,8 @@
+import { type EvidenceKind, type EvidenceRelation, type EvidenceSourceType } from "../types/evidence-taxonomy-target-scope.js";
+export { EVIDENCE_KIND_VALUES, EVIDENCE_RELATION_VALUES, EVIDENCE_SOURCE_TYPE_VALUES, type EvidenceKind, type EvidenceRelation, type EvidenceSourceType, } from "../types/evidence-taxonomy-target-scope.js";
+export declare function assertEvidenceSignedWeight(value: unknown, context: string): number;
+export declare function evidenceRelationFromSignedWeight(weight: number): EvidenceRelation;
+export declare function assertEvidenceRelationMatchesSignedWeight(relation: EvidenceRelation, weight: number, context: string): void;
+export declare function normalizeEvidenceRelationForSignedWeight(relation: unknown, weight: number, context?: string): EvidenceRelation;
+export declare function normalizeEvidenceKind(kind: string | undefined, context?: string): EvidenceKind;
+export declare function normalizeEvidenceSourceType(sourceType: string | undefined, context?: string): EvidenceSourceType;

package/dist/schema-helpers/evidenceAdmission.js

@@ -0,0 +1,167 @@
+import { z } from 'zod';
+import { ConvexError } from 'convex/values';
+
+// src/types/evidence-taxonomy-target-scope.ts
+var EVIDENCE_RELATION_VALUES = ["supports", "contradicts"];
+var EVIDENCE_KIND_VALUES = [
+  "fact",
+  "observation",
+  "claim",
+  "quote",
+  "statistic",
+  "signal"
+];
+var EVIDENCE_METHODOLOGY_VALUES = [
+  "primary_research",
+  "expert_interview",
+  "customer_interview",
+  "field_observation",
+  "proprietary_data",
+  "desk_research",
+  "regulatory_filing",
+  "news_article",
+  "academic_paper",
+  "ai_synthesis",
+  "ai_extraction"
+];
+var EVIDENCE_INFORMATION_ASYMMETRY_VALUES = [
+  "proprietary",
+  "early",
+  "common"
+];
+var EVIDENCE_SOURCE_QUALITY_VALUES = [
+  "primary",
+  "analyzed",
+  "secondary",
+  "tertiary",
+  "unknown"
+];
+var EVIDENCE_SOURCE_TYPE_VALUES = [
+  "human",
+  "ai_extracted",
+  "ai_generated",
+  "imported",
+  "system",
+  "verified",
+  "proprietary"
+];
+var EVIDENCE_SCORING_DIMENSIONS = [
+  "signedImpact",
+  "evidenceRelation",
+  "sourceQuality",
+  "methodology",
+  "informationAsymmetry",
+  "sourceRef",
+  "targetBeliefId",
+  "verificationStatus"
+];
+z.enum(EVIDENCE_RELATION_VALUES);
+z.enum(EVIDENCE_KIND_VALUES);
+z.enum(EVIDENCE_METHODOLOGY_VALUES);
+z.enum(
+  EVIDENCE_INFORMATION_ASYMMETRY_VALUES
+);
+z.enum(
+  EVIDENCE_SOURCE_QUALITY_VALUES
+);
+z.enum(EVIDENCE_SOURCE_TYPE_VALUES);
+z.enum(
+  EVIDENCE_SCORING_DIMENSIONS
+);
+function throwStructuredMutationError(args) {
+  const data = {
+    structuredMutationError: true,
+    message: args.message,
+    status: args.status,
+    code: args.code,
+    invariantCode: args.invariantCode,
+    suggestion: args.suggestion,
+    details: args.details
+  };
+  const error = new ConvexError(
+    data
+  );
+  error.status = args.status;
+  error.code = args.code;
+  error.invariantCode = args.invariantCode;
+  error.suggestion = args.suggestion;
+  error.details = args.details;
+  throw error;
+}
+
+// src/schema-helpers/evidenceAdmission.ts
+var EVIDENCE_KIND_SET = new Set(EVIDENCE_KIND_VALUES);
+var EVIDENCE_SOURCE_TYPE_SET = new Set(EVIDENCE_SOURCE_TYPE_VALUES);
+function assertEvidenceSignedWeight(value, context) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value === 0 || value < -1 || value > 1) {
+    throw new Error(`${context} requires explicit nonzero weight in [-1, 1]`);
+  }
+  return value;
+}
+function evidenceRelationFromSignedWeight(weight) {
+  return weight < 0 ? "contradicts" : "supports";
+}
+function assertEvidenceRelationMatchesSignedWeight(relation, weight, context) {
+  if (relation === "supports" && weight < 0) {
+    throw new Error(`${context} relation supports requires positive weight`);
+  }
+  if (relation === "contradicts" && weight > 0) {
+    throw new Error(`${context} relation contradicts requires negative weight`);
+  }
+}
+function normalizeEvidenceRelationForSignedWeight(relation, weight, context = "Evidence relation") {
+  if (relation === "supports" || relation === "contradicts") {
+    assertEvidenceRelationMatchesSignedWeight(relation, weight, context);
+    return relation;
+  }
+  return evidenceRelationFromSignedWeight(weight);
+}
+function normalizeEvidenceEnumText(value) {
+  return value.trim().toLowerCase();
+}
+function throwEvidenceTaxonomyEnumRefusal(args) {
+  throwStructuredMutationError({
+    status: 400,
+    code: "INVALID_INPUT",
+    message: `[${args.context}] Invalid evidence ${args.field} "${args.value}".`,
+    invariantCode: "evidence.taxonomy_enum",
+    suggestion: `Valid evidence ${args.field} values: ${args.allowed.join(", ")}.`,
+    details: {
+      field: args.field,
+      value: args.value,
+      allowed: args.allowed
+    }
+  });
+}
+function normalizeEvidenceKind(kind, context = "evidence.kind") {
+  if (typeof kind !== "string" || kind.trim().length === 0) {
+    return "observation";
+  }
+  const normalized = normalizeEvidenceEnumText(kind);
+  if (EVIDENCE_KIND_SET.has(normalized)) {
+    return normalized;
+  }
+  throwEvidenceTaxonomyEnumRefusal({
+    field: "kind",
+    value: normalized,
+    allowed: EVIDENCE_KIND_VALUES,
+    context
+  });
+}
+function normalizeEvidenceSourceType(sourceType, context = "evidence.sourceType") {
+  if (typeof sourceType !== "string" || sourceType.trim().length === 0) {
+    return "ai_generated";
+  }
+  const normalized = normalizeEvidenceEnumText(sourceType);
+  if (EVIDENCE_SOURCE_TYPE_SET.has(normalized)) {
+    return normalized;
+  }
+  throwEvidenceTaxonomyEnumRefusal({
+    field: "sourceType",
+    value: normalized,
+    allowed: EVIDENCE_SOURCE_TYPE_VALUES,
+    context
+  });
+}
+
+export { EVIDENCE_KIND_VALUES, EVIDENCE_RELATION_VALUES, EVIDENCE_SOURCE_TYPE_VALUES, assertEvidenceRelationMatchesSignedWeight, assertEvidenceSignedWeight, evidenceRelationFromSignedWeight, normalizeEvidenceKind, normalizeEvidenceRelationForSignedWeight, normalizeEvidenceSourceType };

package/dist/schemas/index.js

@@ -2975,9 +2975,39 @@ var domainEvents = defineTable({
       name: "by_resource",
       columns: ["resourceType", "resourceId", "timestamp"]
     },
+    // OB.2: global chronological order for the Axiom forwarding scan. The
+    // forwarder pages events strictly by (timestamp, eventId) after its
+    // checkpoint cursor, so it needs a total time order independent of topic /
+    // type / tenant. The forwarder additionally tie-breaks on eventId in
+    // application code for events sharing a millisecond timestamp.
+    { kind: "index", name: "by_timestamp", columns: ["timestamp"] },
     { kind: "index", name: "by_expiresAt", columns: ["expiresAt"] }
   ]
 });
+var domainEventForwardCheckpoints = defineTable({
+  name: "domainEventForwardCheckpoints",
+  component: "kernel",
+  category: "events",
+  shape: z.object({
+    // Logical sink name. One checkpoint row per forwarding destination so a
+    // second sink (e.g. a future OTel path) never contends on this cursor.
+    sink: z.string(),
+    // Cursor: the timestamp of the last successfully forwarded event (ms epoch).
+    lastForwardedTimestamp: z.number(),
+    // Cursor tie-breaker: the eventId of the last successfully forwarded event.
+    lastForwardedEventId: z.string(),
+    // Running count of events forwarded through this sink (observability of the
+    // observer — lets an operator confirm the pump is moving without Axiom).
+    forwardedCount: z.number(),
+    // When this checkpoint row was last advanced (ms epoch).
+    updatedAt: z.number(),
+    // Last tick outcome, for at-a-glance health without querying Axiom.
+    lastStatus: z.enum(["ok", "empty", "export_failed"]).optional(),
+    // Redacted last-error summary when lastStatus is export_failed.
+    lastError: z.string().optional()
+  }),
+  indices: [{ kind: "index", name: "by_sink", columns: ["sink"] }]
+});
 var idempotencyTokens = defineTable({
   name: "idempotencyTokens",
   component: "kernel",
@@ -9985,6 +10015,14 @@ DATA_MODEL_MANIFEST_SKELETON.surfaces.map(
   (surface) => surface.compositionEmitted
 );
 var EVIDENCE_RELATION_VALUES = ["supports", "contradicts"];
+var EVIDENCE_KIND_VALUES = [
+  "fact",
+  "observation",
+  "claim",
+  "quote",
+  "statistic",
+  "signal"
+];
 var EVIDENCE_METHODOLOGY_VALUES = [
   "primary_research",
   "expert_interview",
@@ -10038,6 +10076,7 @@ var EVIDENCE_TAXONOMY_REFUSAL_IDS = [
   "metadata_scoring_plan_refused"
 ];
 z.enum(EVIDENCE_RELATION_VALUES);
+z.enum(EVIDENCE_KIND_VALUES);
 z.enum(EVIDENCE_METHODOLOGY_VALUES);
 z.enum(
   EVIDENCE_INFORMATION_ASYMMETRY_VALUES
@@ -13496,6 +13535,7 @@ var KERNEL_TABLE_CONTRACTS = [
   decisionRiskLedger,
   decisionSnapshots,
   domainEvents,
+  domainEventForwardCheckpoints,
   deliberationContributions,
   deliberationSessions,
   stakeholderGroups,