harnery 0.34.0 → 0.35.0

package/dist/core/semantic/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/core/semantic/contract.ts"],"names":[],"mappings":"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"}

package/dist/core/semantic/contract.js

@@ -0,0 +1,230 @@
+import { Type } from "@sinclair/typebox";
+export const SEMANTIC_EVIDENCE_SCHEMA_VERSION = 1;
+export const SEMANTIC_READ_MODEL_SCHEMA_VERSION = 2;
+export const SEMANTIC_EVIDENCE_CONTRACT_VERSION = 1;
+export const SEMANTIC_PROMPT_CONTRACT_VERSION = 3;
+const StrictObject = (properties) => Type.Object(properties, { additionalProperties: false });
+const Timestamp = Type.String({
+    pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$",
+});
+const Sha256 = Type.String({ pattern: "^sha256:[a-f0-9]{64}$" });
+const SafeToken = Type.String({ pattern: "^[a-zA-Z0-9][a-zA-Z0-9._:+-]{0,127}$" });
+const uuidV7Pattern = "[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}";
+const EventId = Type.String({ pattern: `^evt_${uuidV7Pattern}$` });
+const GenerationId = Type.String({ pattern: `^gen_${uuidV7Pattern}$` });
+const InstanceId = Type.String({ pattern: "^inst_[a-zA-Z0-9._-]{1,128}$" });
+export const SEMANTIC_HARNESSES = ["claude-code", "codex", "cursor"];
+export const SEMANTIC_CONFIGURED_MODELS = ["haiku-4.5", "gpt-5.6-luna", "composer-2.5"];
+export const SEMANTIC_PHASES = [
+    "orienting",
+    "researching",
+    "planning",
+    "implementing",
+    "verifying",
+    "coordinating",
+    "waiting",
+    "recovering",
+    "wrapping-up",
+    "unknown",
+];
+/**
+ * Model-synthesized presentation cues. Authoritative operational expressions
+ * such as blocked, waiting, alert, recovering, compacting, observing, strained,
+ * and conducting remain deterministic Codec projections and are excluded.
+ */
+export const SEMANTIC_EXPRESSION_CUES = [
+    "focused",
+    "curious",
+    "deliberating",
+    "investigating",
+    "building",
+    "coordinating",
+    "planning",
+    "verifying",
+    "weighing",
+    "wrapping-up",
+];
+export const SEMANTIC_TAGS = [
+    "research",
+    "planning",
+    "implementation",
+    "verification",
+    "coordination",
+    "waiting",
+    "recovery",
+    "delivery",
+    "documentation",
+    "infrastructure",
+];
+export const SEMANTIC_EVIDENCE_KINDS = [
+    "task",
+    "lifecycle",
+    "intent",
+    "operation",
+    "wait",
+    "progress",
+    "artifact",
+    "action",
+    "terminal",
+    "error",
+    "recovery",
+    "claim-conflict",
+];
+const HarnessSchema = Type.Union(SEMANTIC_HARNESSES.map((value) => Type.Literal(value)));
+const ConfiguredModelSchema = Type.Union(SEMANTIC_CONFIGURED_MODELS.map((value) => Type.Literal(value)));
+const PhaseSchema = Type.Union(SEMANTIC_PHASES.map((value) => Type.Literal(value)));
+const ExpressionCueSchema = Type.Union(SEMANTIC_EXPRESSION_CUES.map((value) => Type.Literal(value)));
+const TagSchema = Type.Union(SEMANTIC_TAGS.map((value) => Type.Literal(value)));
+const EvidenceKindSchema = Type.Union(SEMANTIC_EVIDENCE_KINDS.map((value) => Type.Literal(value)));
+const ConfidenceSchema = Type.Union([
+    Type.Literal("high"),
+    Type.Literal("medium"),
+    Type.Literal("low"),
+]);
+function SemanticFieldSchema(value, options = {}) {
+    const kind = options.kind ?? "synthesis";
+    return StrictObject({
+        value,
+        basis: Type.Literal(kind === "prediction" ? "prediction" : "model-synthesis"),
+        confidence: kind === "prediction"
+            ? Type.Literal("low")
+            : kind === "expression"
+                ? Type.Union([Type.Literal("medium"), Type.Literal("low")])
+                : ConfidenceSchema,
+        evidence_event_ids: Type.Array(EventId, {
+            minItems: options.allowEmptyCitations ? 0 : 1,
+            maxItems: 16,
+            uniqueItems: true,
+        }),
+    });
+}
+export const SemanticEvidenceObservationV1Schema = StrictObject({
+    kind: EvidenceKindSchema,
+    event_id: EventId,
+    observed_at: Timestamp,
+    label: Type.Optional(Type.String({ minLength: 1, maxLength: 120 })),
+    outcome: Type.Optional(SafeToken),
+    error_class: Type.Optional(SafeToken),
+});
+export const SemanticEvidenceV1Schema = StrictObject({
+    schema_version: Type.Literal(SEMANTIC_EVIDENCE_SCHEMA_VERSION),
+    evidence_contract_version: Type.Literal(SEMANTIC_EVIDENCE_CONTRACT_VERSION),
+    instance_id: InstanceId,
+    generation_id: GenerationId,
+    source_harness: HarnessSchema,
+    source: StrictObject({
+        ledger_genesis_id: Type.String({ pattern: "^gex_[a-zA-Z0-9._-]{1,128}$" }),
+        observed_through_event_id: EventId,
+        observed_through_ts: Timestamp,
+    }),
+    task: Type.Optional(StrictObject({ value: Type.String({ minLength: 1, maxLength: 200 }), event_id: EventId })),
+    lifecycle: Type.Optional(StrictObject({ state: SafeToken, event_id: EventId })),
+    intent: Type.Optional(StrictObject({ kind: SafeToken, event_id: EventId })),
+    operation: Type.Optional(StrictObject({
+        category: SafeToken,
+        label: Type.String({ minLength: 1, maxLength: 80 }),
+        event_id: EventId,
+    })),
+    waits: Type.Array(StrictObject({ kind: SafeToken, event_id: EventId, started_at: Timestamp }), {
+        maxItems: 8,
+    }),
+    recent: Type.Array(SemanticEvidenceObservationV1Schema, { maxItems: 8 }),
+    attention: Type.Optional(SemanticEvidenceObservationV1Schema),
+    relationships: Type.Optional(StrictObject({
+        parent_generation_id: Type.Optional(GenerationId),
+        dependency_ids: Type.Array(SafeToken, { maxItems: 16, uniqueItems: true }),
+    })),
+    evidence_event_ids: Type.Array(EventId, { minItems: 1, maxItems: 64, uniqueItems: true }),
+    evidence_digest: Sha256,
+});
+export const SemanticMeaningV2Schema = StrictObject({
+    headline: SemanticFieldSchema(Type.String({ minLength: 1, maxLength: 60 })),
+    summary: SemanticFieldSchema(Type.String({ minLength: 1, maxLength: 240 })),
+    phase: SemanticFieldSchema(PhaseSchema),
+    expression_cue: Type.Optional(SemanticFieldSchema(ExpressionCueSchema, { kind: "expression" })),
+    purpose: Type.Optional(SemanticFieldSchema(Type.String({ minLength: 1, maxLength: 180 }))),
+    recent_result: Type.Optional(SemanticFieldSchema(Type.String({ minLength: 1, maxLength: 180 }))),
+    attention: Type.Optional(SemanticFieldSchema(Type.String({ minLength: 1, maxLength: 180 }))),
+    next_step: Type.Optional(SemanticFieldSchema(Type.String({ minLength: 1, maxLength: 180 }), {
+        kind: "prediction",
+    })),
+    tags: Type.Optional(SemanticFieldSchema(Type.Array(TagSchema, { maxItems: 8, uniqueItems: true }), {
+        allowEmptyCitations: true,
+    })),
+});
+export const SemanticModelReplyV2Schema = StrictObject({
+    schema_version: Type.Literal(SEMANTIC_READ_MODEL_SCHEMA_VERSION),
+    generation_id: GenerationId,
+    evidence_digest: Sha256,
+    meaning: SemanticMeaningV2Schema,
+});
+/** Native structured-output schema bound to one evidence request. */
+export function semanticModelReplyV2SchemaFor(expected) {
+    return StrictObject({
+        schema_version: Type.Literal(SEMANTIC_READ_MODEL_SCHEMA_VERSION),
+        generation_id: Type.Literal(expected.generation_id),
+        evidence_digest: Type.Literal(expected.evidence_digest),
+        meaning: SemanticMeaningV2Schema,
+    });
+}
+const ReaderCommon = {
+    harness: HarnessSchema,
+    configured_model: ConfiguredModelSchema,
+    prompt_contract_version: Type.Literal(SEMANTIC_PROMPT_CONTRACT_VERSION),
+};
+const UnresolvedReaderSchema = StrictObject(ReaderCommon);
+const ResolvedReaderSchema = StrictObject({
+    ...ReaderCommon,
+    resolved_model_id: Type.String({ minLength: 1, maxLength: 160 }),
+    model_attestation: Type.Union([Type.Literal("verified"), Type.Literal("requested-only")]),
+});
+const ReaderSchema = Type.Union([UnresolvedReaderSchema, ResolvedReaderSchema]);
+const ReadModelBase = {
+    schema_version: Type.Literal(SEMANTIC_READ_MODEL_SCHEMA_VERSION),
+    instance_id: InstanceId,
+    generation_id: GenerationId,
+    source: StrictObject({
+        ledger_genesis_id: Type.String({ pattern: "^gex_[a-zA-Z0-9._-]{1,128}$" }),
+        evidence_digest: Sha256,
+        observed_through_event_id: EventId,
+        observed_through_ts: Timestamp,
+    }),
+    generated_at: Timestamp,
+};
+export const SemanticAcceptedReadModelV2Schema = StrictObject({
+    ...ReadModelBase,
+    reader_outcome: Type.Literal("accepted"),
+    reader: ResolvedReaderSchema,
+    meaning: SemanticMeaningV2Schema,
+});
+export const SemanticUnavailableReadModelV2Schema = StrictObject({
+    ...ReadModelBase,
+    reader_outcome: Type.Literal("unavailable"),
+    reader: ReaderSchema,
+    receipt: StrictObject({
+        reason_code: Type.Union([
+            Type.Literal("harness_unavailable"),
+            Type.Literal("authentication_unavailable"),
+            Type.Literal("model_unavailable"),
+            Type.Literal("model_mismatch"),
+        ]),
+    }),
+});
+export const SemanticInvalidReadModelV2Schema = StrictObject({
+    ...ReadModelBase,
+    reader_outcome: Type.Literal("invalid"),
+    reader: ResolvedReaderSchema,
+    receipt: StrictObject({ reason_code: Type.Literal("invalid_output") }),
+});
+export const SemanticDeferredReadModelV2Schema = StrictObject({
+    ...ReadModelBase,
+    reader_outcome: Type.Literal("deferred"),
+    reader: ReaderSchema,
+    receipt: StrictObject({ reason_code: Type.Literal("rate_cap"), eligible_after: Timestamp }),
+});
+export const SemanticAgentReadModelV2Schema = Type.Union([
+    SemanticAcceptedReadModelV2Schema,
+    SemanticUnavailableReadModelV2Schema,
+    SemanticInvalidReadModelV2Schema,
+    SemanticDeferredReadModelV2Schema,
+]);

package/dist/core/semantic/evidence.d.ts

@@ -0,0 +1,11 @@
+import type { V3HeartbeatMaterialization } from "../agents/state/live-coordination-view.js";
+import { type CoordinationViewV3 } from "../events/v3/coordination-view.js";
+import { type ReadLedgerV3Result } from "../events/v3/reader.js";
+import { type SemanticEvidenceV1 } from "./contract.js";
+export declare const SEMANTIC_RECENTLY_ENDED_WINDOW_MS: number;
+/** Read canonical V3 authority and project one privacy-safe envelope per active generation. */
+export declare function buildSemanticEvidenceV1(coordRoot: string, nowMs?: number): SemanticEvidenceV1[];
+/** Pure projection seam used by replay and contract tests. */
+export declare function projectSemanticEvidenceV1(read: ReadLedgerV3Result, liveRows?: readonly V3HeartbeatMaterialization[], nowMs?: number): SemanticEvidenceV1[];
+export declare function projectSemanticEvidenceFromViewV1(read: ReadLedgerV3Result, view: CoordinationViewV3, liveRows?: readonly V3HeartbeatMaterialization[], nowMs?: number): SemanticEvidenceV1[];
+//# sourceMappingURL=evidence.d.ts.map

package/dist/core/semantic/evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../../../src/core/semantic/evidence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,2CAA2C,CAAC;AAG5F,OAAO,EAEL,KAAK,kBAAkB,EAExB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EAAE,KAAK,kBAAkB,EAAgB,MAAM,wBAAwB,CAAC;AAE/E,OAAO,EAIL,KAAK,kBAAkB,EAExB,MAAM,eAAe,CAAC;AAIvB,eAAO,MAAM,iCAAiC,QAAc,CAAC;AAE7D,+FAA+F;AAC/F,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,KAAK,SAAa,GACjB,kBAAkB,EAAE,CAItB;AAED,8DAA8D;AAC9D,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,kBAAkB,EACxB,QAAQ,GAAE,SAAS,0BAA0B,EAAO,EACpD,KAAK,SAAa,GACjB,kBAAkB,EAAE,CAKtB;AAED,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,kBAAkB,EACxB,IAAI,EAAE,kBAAkB,EACxB,QAAQ,GAAE,SAAS,0BAA0B,EAAO,EACpD,KAAK,SAAa,GACjB,kBAAkB,EAAE,CA2BtB"}

package/dist/core/semantic/evidence.js

@@ -0,0 +1,262 @@
+import { readLiveCoordinationRows } from "../agents/state/live-coordination-view.js";
+import { projectCoordinationViewV3, } from "../events/v3/coordination-view.js";
+import { canonicalJsonV3, sha256V3 } from "../events/v3/index.js";
+import { readLedgerV3 } from "../events/v3/reader.js";
+import { projectPresenceCodecDigests } from "../presence/codec-digest.js";
+import { SEMANTIC_EVIDENCE_CONTRACT_VERSION, SEMANTIC_EVIDENCE_SCHEMA_VERSION, } from "./contract.js";
+import { isSemanticPrivacySafe, validateSemanticEvidencePrivacy } from "./validate.js";
+const MAX_RECENT = 8;
+export const SEMANTIC_RECENTLY_ENDED_WINDOW_MS = 30 * 60_000;
+/** Read canonical V3 authority and project one privacy-safe envelope per active generation. */
+export function buildSemanticEvidenceV1(coordRoot, nowMs = Date.now()) {
+    const read = readLedgerV3(coordRoot, { authority: "active" });
+    if (!read.complete || !read.genesis_id)
+        return [];
+    return projectSemanticEvidenceV1(read, readLiveCoordinationRows(coordRoot), nowMs);
+}
+/** Pure projection seam used by replay and contract tests. */
+export function projectSemanticEvidenceV1(read, liveRows = [], nowMs = Date.now()) {
+    if (!read.complete || !read.genesis_id)
+        return [];
+    const view = projectCoordinationViewV3(read);
+    if (!view.authority_safe)
+        return [];
+    return projectSemanticEvidenceFromViewV1(read, view, liveRows, nowMs);
+}
+export function projectSemanticEvidenceFromViewV1(read, view, liveRows = [], nowMs = Date.now()) {
+    if (!read.complete || !read.genesis_id || !view.authority_safe)
+        return [];
+    const events = read.events.map(({ event }) => event);
+    const codec = projectPresenceCodecDigests(events);
+    const rows = new Map(liveRows.map((row) => [row.v3_generation_id, row]));
+    const recentTerminal = Object.values(view.terminal_generations).filter((generation) => {
+        const endedAt = Date.parse(generation.terminal?.observed_at ?? "");
+        return (generation.evidence_complete &&
+            Number.isFinite(endedAt) &&
+            nowMs - endedAt >= 0 &&
+            nowMs - endedAt <= SEMANTIC_RECENTLY_ENDED_WINDOW_MS);
+    });
+    return [...Object.values(view.instances), ...recentTerminal]
+        .filter((generation) => generation.authority_eligible || generation.phase === "terminal")
+        .sort((left, right) => left.generation_id.localeCompare(right.generation_id))
+        .flatMap((generation) => {
+        const evidence = projectGeneration(read.genesis_id, generation, events.filter((event) => eventGenerationId(event) === generation.generation_id), rows.get(generation.generation_id), codec.get(generation.instance_id));
+        return evidence ? [evidence] : [];
+    });
+}
+function projectGeneration(genesisId, generation, events, row, codec) {
+    const start = events.find((event) => event.event_type === "session.started");
+    if (!start || start.event_type !== "session.started")
+        return undefined;
+    const harness = observedHarness(start.payload.runtime_attestation.adapter);
+    if (!harness)
+        return undefined;
+    const latestTask = latest(events, "coord.task_changed");
+    const latestLifecycle = latest(events, "coord.lifecycle_changed");
+    const latestIntent = latest(events, "turn.started");
+    const task = latestTask && row?.task && row.v3_task_state === "set" && isSemanticPrivacySafe(row.task)
+        ? { value: row.task.slice(0, 200), event_id: latestTask.event_id }
+        : undefined;
+    const lifecycle = latestLifecycle
+        ? { state: latestLifecycle.payload.new_state, event_id: latestLifecycle.event_id }
+        : undefined;
+    const intent = latestIntent
+        ? { kind: latestIntent.payload.intent_kind, event_id: latestIntent.event_id }
+        : undefined;
+    const operation = codec?.operation && isSemanticPrivacySafe(codec.operation.label)
+        ? {
+            category: codec.operation.category,
+            label: codec.operation.label,
+            event_id: codec.operation.event_id,
+        }
+        : undefined;
+    const waits = generation.waits.slice(0, 8).map((wait) => ({
+        kind: wait.kind,
+        event_id: wait.started_event_id,
+        started_at: wait.started_at,
+    }));
+    const recent = events.flatMap(toRecentObservation).slice(-MAX_RECENT);
+    const attention = attentionObservation(generation, events, recent);
+    const dependencyIds = generation.waits
+        .map((wait) => wait.authority_reference)
+        .filter((value) => Boolean(value))
+        .filter((value) => /^[a-zA-Z0-9][a-zA-Z0-9._:+-]{0,127}$/.test(value))
+        .slice(0, 16);
+    const relationships = generation.parent_generation_id || dependencyIds.length
+        ? {
+            ...(generation.parent_generation_id
+                ? { parent_generation_id: generation.parent_generation_id }
+                : {}),
+            dependency_ids: [...new Set(dependencyIds)],
+        }
+        : undefined;
+    const evidenceEventIds = unique([
+        start.event_id,
+        task?.event_id,
+        lifecycle?.event_id,
+        intent?.event_id,
+        operation?.event_id,
+        ...waits.map((wait) => wait.event_id),
+        ...recent.map((item) => item.event_id),
+        attention?.event_id,
+    ]).slice(0, 64);
+    const observedThrough = newestEvidenceEvent(events, evidenceEventIds) ?? start;
+    const unsigned = {
+        schema_version: SEMANTIC_EVIDENCE_SCHEMA_VERSION,
+        evidence_contract_version: SEMANTIC_EVIDENCE_CONTRACT_VERSION,
+        instance_id: generation.instance_id,
+        generation_id: generation.generation_id,
+        source_harness: harness,
+        source: {
+            ledger_genesis_id: genesisId,
+            observed_through_event_id: observedThrough.event_id,
+            observed_through_ts: observedThrough.time.observed_at,
+        },
+        ...(task ? { task } : {}),
+        ...(lifecycle ? { lifecycle } : {}),
+        ...(intent ? { intent } : {}),
+        ...(operation ? { operation } : {}),
+        waits,
+        recent,
+        ...(attention ? { attention } : {}),
+        ...(relationships ? { relationships } : {}),
+        evidence_event_ids: evidenceEventIds,
+    };
+    const evidence = {
+        ...unsigned,
+        evidence_digest: sha256V3(canonicalJsonV3(unsigned)),
+    };
+    return validateSemanticEvidencePrivacy(evidence).ok ? evidence : undefined;
+}
+function toRecentObservation(event) {
+    const base = { event_id: event.event_id, observed_at: event.time.observed_at };
+    switch (event.event_type) {
+        case "progress.observed":
+            return [
+                {
+                    ...base,
+                    kind: "progress",
+                    label: progressLabel(event.payload.kind),
+                    outcome: "succeeded",
+                },
+            ];
+        case "artifact.observed":
+            return [
+                {
+                    ...base,
+                    kind: "artifact",
+                    label: artifactLabel(event.payload.operation),
+                    outcome: "succeeded",
+                },
+            ];
+        case "tool.completed":
+            return [
+                {
+                    ...base,
+                    kind: event.payload.outcome === "failed" ? "error" : "action",
+                    label: event.payload.outcome === "succeeded" ? "Tool action succeeded" : "Tool action ended",
+                    outcome: event.payload.outcome,
+                    ...(event.payload.error?.class ? { error_class: event.payload.error.class } : {}),
+                },
+            ];
+        case "command.completed":
+            return [
+                {
+                    ...base,
+                    kind: event.payload.outcome === "failed" ? "error" : "action",
+                    label: event.payload.outcome === "succeeded" ? "Command succeeded" : "Command ended",
+                    outcome: event.payload.outcome,
+                    ...(event.payload.error_class ? { error_class: event.payload.error_class } : {}),
+                },
+            ];
+        case "turn.completed":
+            return [{ ...base, kind: "action", label: "Turn completed", outcome: event.payload.outcome }];
+        case "session.ended":
+            return [
+                { ...base, kind: "terminal", label: "Session ended", outcome: event.payload.outcome },
+            ];
+        case "session.resumed":
+        case "lifecycle.recovered":
+            return [{ ...base, kind: "recovery", label: "Work recovered", outcome: "succeeded" }];
+        case "coord.claim_changed":
+            return event.payload.operation === "denied"
+                ? [{ ...base, kind: "claim-conflict", label: "Write claim conflicted", outcome: "denied" }]
+                : [];
+        default:
+            return [];
+    }
+}
+function attentionObservation(generation, events, recent) {
+    const activeWait = generation.waits.at(-1);
+    if (activeWait) {
+        return {
+            kind: "wait",
+            event_id: activeWait.started_event_id,
+            observed_at: activeWait.started_at,
+            label: `Waiting for ${waitLabel(activeWait.kind)}`,
+        };
+    }
+    const lifecycle = latest(events, "coord.lifecycle_changed");
+    if (lifecycle?.payload.new_state === "blocked") {
+        return {
+            kind: "lifecycle",
+            event_id: lifecycle.event_id,
+            observed_at: lifecycle.time.observed_at,
+            label: "Work is explicitly blocked",
+        };
+    }
+    return [...recent]
+        .reverse()
+        .find((item) => item.kind === "error" || item.kind === "claim-conflict");
+}
+function observedHarness(observation) {
+    if (observation.state !== "observed")
+        return undefined;
+    const id = observation.value.id;
+    return id === "claude-code" || id === "codex" || id === "cursor" ? id : undefined;
+}
+function latest(events, eventType) {
+    return [...events].reverse().find((event) => event.event_type === eventType);
+}
+function eventGenerationId(event) {
+    return "generation_id" in event.scope ? event.scope.generation_id : undefined;
+}
+function newestEvidenceEvent(events, ids) {
+    const allowed = new Set(ids);
+    return [...events].reverse().find((event) => allowed.has(event.event_id));
+}
+function unique(values) {
+    return [...new Set(values.filter((value) => Boolean(value)))];
+}
+function progressLabel(kind) {
+    return ({
+        write: "Files changed",
+        test: "Tests observed",
+        commit: "Commit observed",
+        deploy: "Deployment observed",
+        publication: "Publication observed",
+        review: "Review observed",
+        artifact: "Artifact observed",
+    }[kind] ?? "Progress observed");
+}
+function artifactLabel(operation) {
+    return ({
+        created: "Artifact created",
+        updated: "Artifact updated",
+        viewed: "Artifact viewed",
+        published: "Artifact published",
+    }[operation] ?? "Artifact observed");
+}
+function waitLabel(kind) {
+    return ({
+        permission: "permission",
+        needs_input: "input",
+        operator_input: "operator input",
+        approval: "approval",
+        decision: "a decision",
+        dependency: "a dependency",
+        scheduled: "a scheduled time",
+        rate_limit: "a rate limit",
+        unknown: "attention",
+    }[kind] ?? "attention");
+}

package/dist/core/semantic/index.d.ts

@@ -0,0 +1,10 @@
+export { createSemanticAdapters, discoverSemanticReaders, SEMANTIC_READER_ROUTES, type SemanticAdapter, type SemanticAdapterFailure, type SemanticAdapterResult, type SemanticAdapterSuccess, type SemanticReaderRoute, } from "./adapters.js";
+export { SEMANTIC_CONFIGURED_MODELS, SEMANTIC_EVIDENCE_CONTRACT_VERSION, SEMANTIC_EVIDENCE_KINDS, SEMANTIC_EVIDENCE_SCHEMA_VERSION, SEMANTIC_EXPRESSION_CUES, SEMANTIC_HARNESSES, SEMANTIC_PHASES, SEMANTIC_PROMPT_CONTRACT_VERSION, SEMANTIC_READ_MODEL_SCHEMA_VERSION, SEMANTIC_TAGS, type SemanticAcceptedReadModelV2, SemanticAcceptedReadModelV2Schema, type SemanticAgentReadModelV2, SemanticAgentReadModelV2Schema, type SemanticBasis, type SemanticConfidence, type SemanticConfiguredModel, SemanticDeferredReadModelV2Schema, type SemanticEvidenceKind, type SemanticEvidenceObservationV1, SemanticEvidenceObservationV1Schema, type SemanticEvidenceV1, SemanticEvidenceV1Schema, type SemanticExpressionCue, type SemanticField, type SemanticHarness, SemanticInvalidReadModelV2Schema, type SemanticMeaningV2, SemanticMeaningV2Schema, type SemanticModelReplyV2, SemanticModelReplyV2Schema, type SemanticPhase, type SemanticTag, SemanticUnavailableReadModelV2Schema, } from "./contract.js";
+export { buildSemanticEvidenceV1, projectSemanticEvidenceFromViewV1, projectSemanticEvidenceV1, SEMANTIC_RECENTLY_ENDED_WINDOW_MS, } from "./evidence.js";
+export { type RunSemanticOnceInput, runSemanticOnce, type SemanticOnceOutcome, type SemanticOnceReport, } from "./once.js";
+export { buildSemanticPrompt, extractSemanticJson, SEMANTIC_MAX_REQUEST_BYTES, type SemanticPromptEnvelope, } from "./prompt.js";
+export { activeSemanticCallHistory, enqueueSemanticPending, SEMANTIC_HARD_CALLS_PER_HOUR, SEMANTIC_INVALID_RETRY_COOLDOWN_MS, SEMANTIC_MIN_GENERATION_CALL_INTERVAL_MS, selectSemanticPending, semanticDocumentEligible, semanticGenerationCallEligible, semanticPriorityBand, semanticRateCap, } from "./scheduler.js";
+export { acquireSemanticServiceLease, type EnsureSemanticServiceDependencies, type EnsureSemanticServiceResult, type EnsureSemanticServiceState, ensureSemanticServiceRunning, type RunSemanticServiceDaemonInput, readSemanticServiceStatus, requestSemanticServiceStop, runSemanticServiceDaemon, SEMANTIC_SERVICE_DEFAULT_DEBOUNCE_MS, SEMANTIC_SERVICE_DEFAULT_HEARTBEAT_MS, SEMANTIC_SERVICE_DEFAULT_WAKE_MS, SEMANTIC_SERVICE_STATUS_SCHEMA_VERSION, type SemanticServiceErrorCode, type SemanticServiceState, type SemanticServiceStatus, type SemanticServiceStatusRecord, spawnSemanticService, } from "./service.js";
+export { inspectSemanticDocument, invalidateSemanticDerivedState, listSemanticAgentDocuments, pruneSemanticStorage, readSemanticAgentDocument, readSemanticCache, readSemanticManifest, SEMANTIC_MANIFEST_SCHEMA_VERSION, type SemanticCacheIdentity, type SemanticCallReceipt, type SemanticManifestV2, type SemanticPendingItem, type SemanticReaderResolution, semanticCacheKey, semanticConfigurationDigest, semanticPaths, writeSemanticAgentDocument, writeSemanticCache, writeSemanticManifest, } from "./storage.js";
+export { isSemanticPrivacySafe, type SemanticValidationFailure, type SemanticValidationResult, type SemanticValidationSuccess, semanticPrivacyIssue, validateSemanticEvidencePrivacy, validateSemanticModelReply, validateSemanticReadModel, } from "./validate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/semantic/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/semantic/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACtB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,GACzB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,0BAA0B,EAC1B,kCAAkC,EAClC,uBAAuB,EACvB,gCAAgC,EAChC,wBAAwB,EACxB,kBAAkB,EAClB,eAAe,EACf,gCAAgC,EAChC,kCAAkC,EAClC,aAAa,EACb,KAAK,2BAA2B,EAChC,iCAAiC,EACjC,KAAK,wBAAwB,EAC7B,8BAA8B,EAC9B,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,iCAAiC,EACjC,KAAK,oBAAoB,EACzB,KAAK,6BAA6B,EAClC,mCAAmC,EACnC,KAAK,kBAAkB,EACvB,wBAAwB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,gCAAgC,EAChC,KAAK,iBAAiB,EACtB,uBAAuB,EACvB,KAAK,oBAAoB,EACzB,0BAA0B,EAC1B,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,oCAAoC,GACrC,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,uBAAuB,EACvB,iCAAiC,EACjC,yBAAyB,EACzB,iCAAiC,GAClC,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,oBAAoB,EACzB,eAAe,EACf,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACxB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,0BAA0B,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,yBAAyB,EACzB,sBAAsB,EACtB,4BAA4B,EAC5B,kCAAkC,EAClC,wCAAwC,EACxC,qBAAqB,EACrB,wBAAwB,EACxB,8BAA8B,EAC9B,oBAAoB,EACpB,eAAe,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,2BAA2B,EAC3B,KAAK,iCAAiC,EACtC,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,4BAA4B,EAC5B,KAAK,6BAA6B,EAClC,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,EACxB,oCAAoC,EACpC,qCAAqC,EACrC,gCAAgC,EAChC,sCAAsC,EACtC,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,oBAAoB,GACrB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,uBAAuB,EACvB,8BAA8B,EAC9B,0BAA0B,EAC1B,oBAAoB,EACpB,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,EACpB,gCAAgC,EAChC,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,gBAAgB,EAChB,2BAA2B,EAC3B,aAAa,EACb,0BAA0B,EAC1B,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,qBAAqB,EACrB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,oBAAoB,EACpB,+BAA+B,EAC/B,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,eAAe,CAAC"}

package/dist/core/semantic/index.js

@@ -0,0 +1,9 @@
+export { createSemanticAdapters, discoverSemanticReaders, SEMANTIC_READER_ROUTES, } from "./adapters.js";
+export { SEMANTIC_CONFIGURED_MODELS, SEMANTIC_EVIDENCE_CONTRACT_VERSION, SEMANTIC_EVIDENCE_KINDS, SEMANTIC_EVIDENCE_SCHEMA_VERSION, SEMANTIC_EXPRESSION_CUES, SEMANTIC_HARNESSES, SEMANTIC_PHASES, SEMANTIC_PROMPT_CONTRACT_VERSION, SEMANTIC_READ_MODEL_SCHEMA_VERSION, SEMANTIC_TAGS, SemanticAcceptedReadModelV2Schema, SemanticAgentReadModelV2Schema, SemanticDeferredReadModelV2Schema, SemanticEvidenceObservationV1Schema, SemanticEvidenceV1Schema, SemanticInvalidReadModelV2Schema, SemanticMeaningV2Schema, SemanticModelReplyV2Schema, SemanticUnavailableReadModelV2Schema, } from "./contract.js";
+export { buildSemanticEvidenceV1, projectSemanticEvidenceFromViewV1, projectSemanticEvidenceV1, SEMANTIC_RECENTLY_ENDED_WINDOW_MS, } from "./evidence.js";
+export { runSemanticOnce, } from "./once.js";
+export { buildSemanticPrompt, extractSemanticJson, SEMANTIC_MAX_REQUEST_BYTES, } from "./prompt.js";
+export { activeSemanticCallHistory, enqueueSemanticPending, SEMANTIC_HARD_CALLS_PER_HOUR, SEMANTIC_INVALID_RETRY_COOLDOWN_MS, SEMANTIC_MIN_GENERATION_CALL_INTERVAL_MS, selectSemanticPending, semanticDocumentEligible, semanticGenerationCallEligible, semanticPriorityBand, semanticRateCap, } from "./scheduler.js";
+export { acquireSemanticServiceLease, ensureSemanticServiceRunning, readSemanticServiceStatus, requestSemanticServiceStop, runSemanticServiceDaemon, SEMANTIC_SERVICE_DEFAULT_DEBOUNCE_MS, SEMANTIC_SERVICE_DEFAULT_HEARTBEAT_MS, SEMANTIC_SERVICE_DEFAULT_WAKE_MS, SEMANTIC_SERVICE_STATUS_SCHEMA_VERSION, spawnSemanticService, } from "./service.js";
+export { inspectSemanticDocument, invalidateSemanticDerivedState, listSemanticAgentDocuments, pruneSemanticStorage, readSemanticAgentDocument, readSemanticCache, readSemanticManifest, SEMANTIC_MANIFEST_SCHEMA_VERSION, semanticCacheKey, semanticConfigurationDigest, semanticPaths, writeSemanticAgentDocument, writeSemanticCache, writeSemanticManifest, } from "./storage.js";
+export { isSemanticPrivacySafe, semanticPrivacyIssue, validateSemanticEvidencePrivacy, validateSemanticModelReply, validateSemanticReadModel, } from "./validate.js";

package/dist/core/semantic/once.d.ts

@@ -0,0 +1,33 @@
+import { type SemanticAdapter } from "./adapters.js";
+import { type SemanticEvidenceV1, type SemanticHarness } from "./contract.js";
+export interface SemanticOnceOutcome {
+    generation_id: string;
+    source_harness: SemanticHarness;
+    action: "unchanged" | "cached" | "accepted" | "unavailable" | "invalid" | "deferred";
+    model_call: boolean;
+    duration_ms?: number;
+    input_bytes?: number;
+    output_bytes?: number;
+}
+export interface SemanticOnceReport {
+    schema_version: 1;
+    ledger_genesis_id?: string;
+    evidence_count: number;
+    evidence_by_harness: Record<SemanticHarness, number>;
+    model_calls: number;
+    cache_hits: number;
+    outcomes: SemanticOnceOutcome[];
+    completed_at: string;
+}
+export interface RunSemanticOnceInput {
+    coordRoot: string;
+    evidence?: SemanticEvidenceV1[];
+    adapters?: Record<SemanticHarness, SemanticAdapter>;
+    now?: () => Date;
+    callsPerHour?: number;
+    debounceMs?: number;
+    minimumGenerationCallIntervalMs?: number;
+    shouldStop?: () => boolean;
+}
+export declare function runSemanticOnce(input: RunSemanticOnceInput): Promise<SemanticOnceReport>;
+//# sourceMappingURL=once.d.ts.map

package/dist/core/semantic/once.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"once.d.ts","sourceRoot":"","sources":["../../../src/core/semantic/once.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,eAAe,CAAC;AACvB,OAAO,EAIL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACrB,MAAM,eAAe,CAAC;AA4BvB,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,eAAe,CAAC;IAChC,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,UAAU,GAAG,aAAa,GAAG,SAAS,GAAG,UAAU,CAAC;IACrF,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,CAAC,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC;IACpD,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+BAA+B,CAAC,EAAE,MAAM,CAAC;IACzC,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC;CAC5B;AAED,wBAAsB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAmL9F"}