@sigloch/contracts 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sigloch Consulting
+
+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/dist/harness/index.d.ts

@@ -0,0 +1,185 @@
+/**
+ * @sigloch/contracts/harness — Graph-Harness interface contracts (D1).
+ *
+ * Single source of truth for the graphcode Apply-Gate surface:
+ *   HarnessConfig · MutateCommand · MutateResult.
+ * Reconciled to the graph-api-core `Graph` model (uid/type/name on nodes,
+ * sourceId/targetId/edgeType on edges) — NOT the contracts/se OntologyGraph
+ * shape. Owned here (D1) so harness/MCP/hooks share one Zod schema instead of
+ * each redefining it locally (no parallel paths).
+ *
+ * @author andreas@siglochconsulting
+ */
+import { z } from 'zod/v4';
+export declare const HarnessConfigSchema: z.ZodObject<{
+    repoRoot: z.ZodString;
+    scope: z.ZodObject<{
+        workspaceId: z.ZodString;
+        systemId: z.ZodString;
+    }, z.core.$strip>;
+    consumerType: z.ZodDefault<z.ZodEnum<{
+        human: "human";
+        agent: "agent";
+        system: "system";
+    }>>;
+    preCommitTimeout: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type HarnessConfig = z.infer<typeof HarnessConfigSchema>;
+export declare const MutateCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    op: z.ZodLiteral<"add-node">;
+    node: z.ZodObject<{
+        uid: z.ZodString;
+        type: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        attributes: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"update-node">;
+    node: z.ZodObject<{
+        uid: z.ZodString;
+        type: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"delete-node">;
+    uid: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"add-edge">;
+    edge: z.ZodObject<{
+        sourceId: z.ZodString;
+        targetId: z.ZodString;
+        edgeType: z.ZodString;
+        attributes: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"delete-edge">;
+    edge: z.ZodObject<{
+        sourceId: z.ZodString;
+        targetId: z.ZodString;
+        edgeType: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"update-edge">;
+    edge: z.ZodObject<{
+        sourceId: z.ZodString;
+        targetId: z.ZodString;
+        edgeType: z.ZodString;
+    }, z.core.$strip>;
+    set: z.ZodObject<{
+        edgeType: z.ZodOptional<z.ZodString>;
+        flip: z.ZodOptional<z.ZodBoolean>;
+        attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"merge-nodes">;
+    sourceUid: z.ZodString;
+    targetUid: z.ZodString;
+}, z.core.$strip>], "op">;
+export type MutateCommand = z.infer<typeof MutateCommandSchema>;
+/** Monotone graph revision; incremented by +1 per successful mutate(). */
+export declare const GraphVersionSchema: z.ZodNumber;
+export type GraphVersion = z.infer<typeof GraphVersionSchema>;
+/** Optional second arg to harness.mutate(commands, options?). */
+export declare const MutateOptionsSchema: z.ZodObject<{
+    baseVersion: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type MutateOptions = z.infer<typeof MutateOptionsSchema>;
+/** One applied batch between `sinceVersion` and `currentVersion`. */
+export declare const StaleDeltaEntrySchema: z.ZodObject<{
+    graphVersion: z.ZodNumber;
+    ts: z.ZodString;
+    changedUids: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type StaleDeltaEntry = z.infer<typeof StaleDeltaEntrySchema>;
+export declare const StaleDeltaSchema: z.ZodObject<{
+    sinceVersion: z.ZodNumber;
+    currentVersion: z.ZodNumber;
+    entries: z.ZodArray<z.ZodObject<{
+        graphVersion: z.ZodNumber;
+        ts: z.ZodString;
+        changedUids: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    changedUids: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type StaleDelta = z.infer<typeof StaleDeltaSchema>;
+export declare const RuleViolationSchema: z.ZodObject<{
+    ruleId: z.ZodString;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+        info: "info";
+    }>;
+    message: z.ZodString;
+    elementId: z.ZodOptional<z.ZodString>;
+    fixHint: z.ZodOptional<z.ZodString>;
+    context: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export type RuleViolation = z.infer<typeof RuleViolationSchema>;
+/** Apply tier derived from violation severity (3-tier gate, R1). */
+export declare const MutateTier: z.ZodEnum<{
+    "auto-apply": "auto-apply";
+    suggest: "suggest";
+    block: "block";
+}>;
+export type MutateTier = z.infer<typeof MutateTier>;
+export declare const MutateResultSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    appliedCommands: z.ZodNumber;
+    mutations: z.ZodNumber;
+    violations: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        ruleId: z.ZodString;
+        severity: z.ZodEnum<{
+            error: "error";
+            warning: "warning";
+            info: "info";
+        }>;
+        message: z.ZodString;
+        elementId: z.ZodOptional<z.ZodString>;
+        fixHint: z.ZodOptional<z.ZodString>;
+        context: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>>;
+    confidence: z.ZodOptional<z.ZodNumber>;
+    tier: z.ZodOptional<z.ZodEnum<{
+        "auto-apply": "auto-apply";
+        suggest: "suggest";
+        block: "block";
+    }>>;
+    trajectoryId: z.ZodOptional<z.ZodString>;
+    graphVersion: z.ZodOptional<z.ZodNumber>;
+    stale: z.ZodOptional<z.ZodBoolean>;
+    staleDelta: z.ZodOptional<z.ZodObject<{
+        sinceVersion: z.ZodNumber;
+        currentVersion: z.ZodNumber;
+        entries: z.ZodArray<z.ZodObject<{
+            graphVersion: z.ZodNumber;
+            ts: z.ZodString;
+            changedUids: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+        changedUids: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type MutateResult = z.infer<typeof MutateResultSchema>;
+/** Domains a mutation may invalidate (superset; always at least ['graph']). */
+export declare const UpdateDomainSchema: z.ZodEnum<{
+    graph: "graph";
+    rules: "rules";
+    readiness: "readiness";
+    suggestions: "suggestions";
+}>;
+export type UpdateDomain = z.infer<typeof UpdateDomainSchema>;
+/** Emitted once per mutation; an SSE handler serialises it as an `invalidate` event. */
+export declare const LiveUpdateEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"invalidate">;
+    domains: z.ZodArray<z.ZodEnum<{
+        graph: "graph";
+        rules: "rules";
+        readiness: "readiness";
+        suggestions: "suggestions";
+    }>>;
+    ts: z.ZodString;
+    version: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type LiveUpdateEvent = z.infer<typeof LiveUpdateEventSchema>;

package/dist/harness/index.js

@@ -0,0 +1,185 @@
+/**
+ * @sigloch/contracts/harness — Graph-Harness interface contracts (D1).
+ *
+ * Single source of truth for the graphcode Apply-Gate surface:
+ *   HarnessConfig · MutateCommand · MutateResult.
+ * Reconciled to the graph-api-core `Graph` model (uid/type/name on nodes,
+ * sourceId/targetId/edgeType on edges) — NOT the contracts/se OntologyGraph
+ * shape. Owned here (D1) so harness/MCP/hooks share one Zod schema instead of
+ * each redefining it locally (no parallel paths).
+ *
+ * @author andreas@siglochconsulting
+ */
+import { z } from 'zod/v4';
+// ---------------------------------------------------------------------------
+// HarnessConfig — one harness instance per repo (single Kuzu owner).
+// ---------------------------------------------------------------------------
+export const HarnessConfigSchema = z.object({
+    /** Repo root; the Kuzu store lives at `<repoRoot>/.graphcode/kuzu`. */
+    repoRoot: z.string(),
+    /** Graph scope this harness owns. */
+    scope: z.object({
+        workspaceId: z.string(),
+        systemId: z.string(),
+    }),
+    /** Who is driving the harness; logged on mutations, never used to skip the gate (L1). */
+    consumerType: z.enum(['human', 'agent', 'system']).default('agent'),
+    /** Pre-commit hook timeout in ms. */
+    preCommitTimeout: z.number().int().positive().default(5000),
+});
+// ---------------------------------------------------------------------------
+// MutateCommand — discriminated union over the four graph mutations.
+// Node payloads use uid/type/name; edge payloads use sourceId/targetId/edgeType.
+// ---------------------------------------------------------------------------
+const NodePayloadSchema = z.object({
+    uid: z.string(),
+    type: z.string(),
+    name: z.string(),
+    description: z.string().optional(),
+    attributes: z.record(z.string(), z.unknown()).default({}),
+});
+const NodePatchSchema = z.object({
+    uid: z.string(),
+    type: z.string().optional(),
+    name: z.string().optional(),
+    description: z.string().optional(),
+    attributes: z.record(z.string(), z.unknown()).optional(),
+});
+const EdgePayloadSchema = z.object({
+    sourceId: z.string(),
+    targetId: z.string(),
+    edgeType: z.string(),
+    attributes: z.record(z.string(), z.unknown()).default({}),
+});
+export const MutateCommandSchema = z.discriminatedUnion('op', [
+    z.object({ op: z.literal('add-node'), node: NodePayloadSchema }),
+    z.object({ op: z.literal('update-node'), node: NodePatchSchema }),
+    z.object({ op: z.literal('delete-node'), uid: z.string() }),
+    z.object({ op: z.literal('add-edge'), edge: EdgePayloadSchema }),
+    z.object({
+        op: z.literal('delete-edge'),
+        edge: z.object({
+            sourceId: z.string(),
+            targetId: z.string(),
+            edgeType: z.string(),
+        }),
+    }),
+    // CR-196: Typwechsel und/oder Richtungswechsel als EIN semantischer Op —
+    // im Audit unterscheidbar von delete+add (Flip ≠ Delete+Add).
+    z.object({
+        op: z.literal('update-edge'),
+        /** Identität der bestehenden Kante. */
+        edge: z.object({
+            sourceId: z.string(),
+            targetId: z.string(),
+            edgeType: z.string(),
+        }),
+        /** Änderung; mindestens ein Feld muss gesetzt sein. */
+        set: z
+            .object({
+            edgeType: z.string().optional(),
+            flip: z.boolean().optional(),
+            attributes: z.record(z.string(), z.unknown()).optional(),
+        })
+            .refine((s) => s.edgeType !== undefined || s.flip !== undefined || s.attributes !== undefined, {
+            message: 'update-edge.set requires at least one of edgeType|flip|attributes',
+        }),
+    }),
+    // CR-196: target absorbiert source — Kanten umgehängt, source gelöscht,
+    // Gate prüft den Ergebnisgraph (R-18); keine Client-komponierten Batches.
+    z.object({
+        op: z.literal('merge-nodes'),
+        sourceUid: z.string(),
+        targetUid: z.string(),
+    }),
+]);
+// ---------------------------------------------------------------------------
+// CR-199: OCC — graph revision + optional baseVersion on mutate().
+// Schema-only here; revision counter/stale-check/delta live in the harness
+// (graphcode follow-up CR). Additive: omitting baseVersion keeps today's
+// last-write-wins behavior (no conflict check).
+// ---------------------------------------------------------------------------
+/** Monotone graph revision; incremented by +1 per successful mutate(). */
+export const GraphVersionSchema = z.number().int().nonnegative();
+/** Optional second arg to harness.mutate(commands, options?). */
+export const MutateOptionsSchema = z.object({
+    baseVersion: GraphVersionSchema.optional(),
+});
+// ---------------------------------------------------------------------------
+// CR-200: staleDelta aligned with graphcode CR-GC-233's proven shape — the
+// applied batches since `sinceVersion`, not just a flattened UID projection.
+// `changedUids` stays as the union convenience field (CR-199).
+// ---------------------------------------------------------------------------
+/** One applied batch between `sinceVersion` and `currentVersion`. */
+export const StaleDeltaEntrySchema = z.object({
+    /** Graph revision produced by this batch. */
+    graphVersion: GraphVersionSchema,
+    /** ISO timestamp the batch was applied. */
+    ts: z.string(),
+    /** Elements this batch touched. */
+    changedUids: z.array(z.string()),
+});
+export const StaleDeltaSchema = z.object({
+    sinceVersion: GraphVersionSchema,
+    currentVersion: GraphVersionSchema,
+    /** Applied batches since sinceVersion, in order. */
+    entries: z.array(StaleDeltaEntrySchema),
+    /** Union of entries[].changedUids — convenience for callers that only need invalidation targets. */
+    changedUids: z.array(z.string()),
+});
+// ---------------------------------------------------------------------------
+// MutateResult — outcome of the Apply-Gate, incl. 3-tier confidence (R1).
+// ---------------------------------------------------------------------------
+export const RuleViolationSchema = z.object({
+    ruleId: z.string(),
+    severity: z.enum(['error', 'warning', 'info']),
+    message: z.string(),
+    elementId: z.string().optional(),
+    /** CR-GC-203 item 1: how to fix this violation (carried from the contracts rule). */
+    fixHint: z.string().optional(),
+    /** Fix-context (candidate_targets, existing_traces, …) so an agent resolves the
+     * violation from the payload — no extra DB queries. Validated upstream in se/rules.ts. */
+    context: z.unknown().optional(),
+});
+/** Apply tier derived from violation severity (3-tier gate, R1). */
+export const MutateTier = z.enum(['auto-apply', 'suggest', 'block']);
+export const MutateResultSchema = z.object({
+    /** false iff a pre-commit hook blocked or an error-severity rule fired. */
+    success: z.boolean(),
+    /** Number of commands applied in-memory before evaluation. */
+    appliedCommands: z.number().int().nonnegative(),
+    /** Net node/edge mutations persisted (0 when blocked). */
+    mutations: z.number().int().nonnegative(),
+    /** All rule violations from evaluateRules (empty when clean). */
+    violations: z.array(RuleViolationSchema).default([]),
+    /** Confidence 0..1; defaults to 1 for deterministic human/system edits. */
+    confidence: z.number().min(0).max(1).optional(),
+    /** Gate decision tier: block (error) | suggest (warning) | auto-apply (clean). */
+    tier: MutateTier.optional(),
+    /** Set by CR-102 when a trajectory is recorded; absent here. */
+    trajectoryId: z.string().optional(),
+    /** CR-199: graph revision after apply (success only). */
+    graphVersion: GraphVersionSchema.optional(),
+    /** CR-199: true iff baseVersion != current revision — nothing applied, no rule evaluation ran. */
+    stale: z.boolean().optional(),
+    /** CR-199/CR-200: present iff stale — the delta for client re-read + retry. */
+    staleDelta: StaleDeltaSchema.optional(),
+});
+// ---------------------------------------------------------------------------
+// LiveUpdateEvent — the SSE invalidation contract (CR-GC-109).
+// Defined ONCE here so the emitting harness AND the dashboard/host-bridge that
+// consume the SSE stream share one Zod schema (no fork, analog D1). graphcode
+// src/emit.ts re-exports these; the host serialises a LiveUpdateEvent per
+// mutation, the viewer parses it with LiveUpdateEventSchema.
+// ---------------------------------------------------------------------------
+/** Domains a mutation may invalidate (superset; always at least ['graph']). */
+export const UpdateDomainSchema = z.enum(['graph', 'rules', 'readiness', 'suggestions']);
+/** Emitted once per mutation; an SSE handler serialises it as an `invalidate` event. */
+export const LiveUpdateEventSchema = z.object({
+    type: z.literal('invalidate'),
+    domains: z.array(UpdateDomainSchema),
+    /** ISO timestamp of when the event was produced. */
+    ts: z.string(),
+    /** CR-199: graph revision after the mutation that triggered this event. */
+    version: GraphVersionSchema.optional(),
+});

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @sigloch/contracts
+ * Zod-based contracts as single source of truth for the SE model layer.
+ *
+ * Scope is `se` (ontology + rules) plus the `harness` schemas on the `./harness`
+ * subpath. Domain ontologies live in their product repo, not here (CR-205): the
+ * finance ontology moved to moneyflow, and the empty `immo`/`content` subtrees —
+ * with their exports pointing at files that were never built — are gone.
+ *
+ * @author andreas@siglochconsulting
+ */
+export * as se from './se/index.js';
+export { z } from 'zod/v4';

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @sigloch/contracts
+ * Zod-based contracts as single source of truth for the SE model layer.
+ *
+ * Scope is `se` (ontology + rules) plus the `harness` schemas on the `./harness`
+ * subpath. Domain ontologies live in their product repo, not here (CR-205): the
+ * finance ontology moved to moneyflow, and the empty `immo`/`content` subtrees —
+ * with their exports pointing at files that were never built — are gone.
+ *
+ * @author andreas@siglochconsulting
+ */
+// Domain exports
+export * as se from './se/index.js';
+export { z } from 'zod/v4';

package/dist/se/ao-rules.d.ts

@@ -0,0 +1,59 @@
+/**
+ * CR-159: AO-D Architecture Optimization Detection Rules.
+ * Severity: info (optimization hints [OH], not blocking violations).
+ */
+import type { OntologyGraph } from './ontology.js';
+import type { RuleViolation } from './rules.js';
+/**
+ * AO-D01: Relay Node Detection.
+ * A FUNC is a relay if it (a) satisfies no REQ, (b) has >=2 outgoing io to FUNCs,
+ * and (c) target FUNCs share SCHEMA overlap >= 0.5 (via ND-02 matrix, skipped if unavailable).
+ */
+export declare function aoD01RelayNode(graph: OntologyGraph): RuleViolation[];
+/**
+ * AO-D03: Duplicate Path Detection.
+ * FUNC A sends io to both B and C, where B and C connect to the same SCHEMA elements.
+ */
+export declare function aoD03DuplicatePath(graph: OntologyGraph): RuleViolation[];
+export declare function cr01CrossingFlowCount(graph: OntologyGraph): RuleViolation[];
+export declare function rt01PhysicalBoundaryIntegrity(graph: OntologyGraph): RuleViolation[];
+export declare function ph01PhysicalModCompleteness(graph: OntologyGraph): RuleViolation[];
+export declare function ca01CapabilityAllocation(graph: OntologyGraph): RuleViolation[];
+export declare function io01CrossModuleCompleteness(graph: OntologyGraph): RuleViolation[];
+export declare const AO_RULES: readonly [{
+    readonly id: "AO-D01";
+    readonly name: "RelayNodeDetection";
+    readonly severity: "info";
+    readonly evaluate: typeof aoD01RelayNode;
+}, {
+    readonly id: "AO-D03";
+    readonly name: "DuplicatePathDetection";
+    readonly severity: "info";
+    readonly evaluate: typeof aoD03DuplicatePath;
+}, {
+    readonly id: "CR-01";
+    readonly name: "CrossingFlowCount";
+    readonly severity: "warning";
+    readonly evaluate: typeof cr01CrossingFlowCount;
+}, {
+    readonly id: "RT-01";
+    readonly name: "PhysicalBoundaryIntegrity";
+    readonly severity: "error";
+    readonly evaluate: typeof rt01PhysicalBoundaryIntegrity;
+}, {
+    readonly id: "PH-01";
+    readonly name: "PhysicalModCompleteness";
+    readonly severity: "info";
+    readonly evaluate: typeof ph01PhysicalModCompleteness;
+}, {
+    readonly id: "CA-01";
+    readonly name: "CapabilityAllocation";
+    readonly severity: "error";
+    readonly evaluate: typeof ca01CapabilityAllocation;
+}, {
+    readonly id: "IO-01";
+    readonly name: "CrossModuleIOCompleteness";
+    readonly severity: "warning";
+    readonly evaluate: typeof io01CrossModuleCompleteness;
+}];
+export declare function evaluateAORules(graph: OntologyGraph): RuleViolation[];