@groundnuty/macf-core 0.2.35 → 0.2.37

package/dist/index.d.ts

@@ -17,6 +17,9 @@ export * from './config.js';
 export * from './token.js';
 export * from './types.js';
 export * from './semver.js';
+export * from './reflection.js';
+export * from './norm.js';
+export * from './protected-invariant-norms.js';
 export * from './mtls-health-ping.js';
 export * from './certs/index.js';
 export * from './registry/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AAIpC,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAC5F,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AAIpC,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAC5F,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/index.js

@@ -17,6 +17,9 @@ export * from './config.js';
 export * from './token.js';
 export * from './types.js';
 export * from './semver.js';
+export * from './reflection.js';
+export * from './norm.js';
+export * from './protected-invariant-norms.js';
 export * from './mtls-health-ping.js';
 export * from './certs/index.js';
 export * from './registry/index.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AAEpC,kEAAkE;AAClE,oEAAoE;AACpE,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AAEpC,kEAAkE;AAClE,oEAAoE;AACpE,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/norm.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Versioned structured-norm (Moise-style) representation + deontic
+ * conflict-checker (groundnuty/macf#504, DR-026 G2 — PR-1).
+ *
+ * This module gives the coordination protocol a *machine-checkable* form for
+ * its norms. A "norm" is a deontic statement — an obligation, permission, or
+ * prohibition — bound to a `(role, action, condition)` triple. G3's SECP
+ * invariant-validator (macf#505) consumes this representation to mechanically
+ * check that a proposed rule change never contradicts a protected invariant.
+ *
+ * --------------------------------------------------------------------------
+ * G2 MODELS, IT DOES NOT ENFORCE.
+ * --------------------------------------------------------------------------
+ * This is a *data model* only. The runtime governor is the existing set of
+ * `check-*.sh` PreToolUse/PostToolUse hooks plus the DR-026 auditor — they
+ * are what actually block/warn at tool-call time. `SceneSchema` below models
+ * the issue-lifecycle scene as data (states + transitions); it carries NO
+ * enforcement code. Nothing here runs at coordination time.
+ *
+ * --------------------------------------------------------------------------
+ * CONTROLLED VOCABULARIES — the load-bearing guardrail.
+ * --------------------------------------------------------------------------
+ * The conflict-checker matches norms on three keys: `role`, `action`,
+ * `condition`. If two genuinely-conflicting norms are spelled differently
+ * (`after_merge` vs `after-merge`), a naive checker silently fails to match
+ * them — producing FALSE CONFIDENCE, which is worse than no checker at all.
+ *
+ * To close that silent-miss, every match-key is a CLOSED Zod enum over a
+ * canonical token set, and `normalizeToken` is applied to inputs first
+ * (lowercase, collapse runs of `_`/whitespace/`-` to a single `-`). An
+ * unknown token after normalization is REJECTED by the schema, forcing a
+ * deliberate vocabulary extension rather than an accidental synonym.
+ *
+ * --------------------------------------------------------------------------
+ * POSITIVE-ACTION CONVENTION.
+ * --------------------------------------------------------------------------
+ * The `Action` enum carries ONLY positive actions (`self-merge`,
+ * `close-issue`, …) — NEVER negated forms (`not-self-merge`). Negation lives
+ * exclusively in the `deontic` field. This is deliberate: if negated actions
+ * were allowed, a `prohibition(merge-pr)` could be silently dodged by
+ * re-expressing it as `obligation(not-merge-pr)` — the same constraint under
+ * a key the conflict-checker would never group together. Keeping actions
+ * positive means a clash on a constraint is always visible on one shared key.
+ *
+ * --------------------------------------------------------------------------
+ * DEONTIC-CONFLICT MATRIX (within one (role, action, condition) group).
+ * --------------------------------------------------------------------------
+ *   obligation  ∧ prohibition  → CONFLICT  ("must" vs "must not")
+ *   permission  ∧ prohibition  → CONFLICT  ("may"  vs "must not")
+ *   obligation  ∧ permission   → consistent (obligation ⊨ permission)
+ * Same deontic on the same key is not a logical conflict; duplicate
+ * obligations get a NON-BLOCKING warning (likely a redundant rule).
+ *
+ * v1 SCOPE: matching is exact-token on the canonical triple. Condition
+ * subsumption (one condition implies another), temporal/deadline logic, and
+ * role-hierarchy inheritance are DEFERRED to the G3 increment (macf#505).
+ */
+import { z } from 'zod';
+/** Current norm schema version. Bump on a breaking shape change. */
+export declare const NORM_SCHEMA_VERSION: "1.0";
+/** Stable type-tag distinguishing norm records on a multi-kind ledger. */
+export declare const NORM_KIND: "macf.norm";
+/**
+ * Canonicalize a vocabulary token: lowercase, then collapse any run of
+ * underscores / whitespace / hyphens into a single hyphen, and trim leading
+ * and trailing hyphens. This is what makes `after_merge`, `after merge`,
+ * `After-Merge`, and `after--merge` all map to the ONE canonical token
+ * `after-merge`. Applied to every match-key before enum validation so the
+ * enum only ever sees canonical forms.
+ */
+export declare function normalizeToken(s: string): string;
+/**
+ * Canonical ROLE vocabulary — the coordination actors a norm can bind to.
+ * Closed set: an unknown role is rejected (extend deliberately).
+ */
+export declare const ROLE_TOKENS: readonly ["reporter", "implementer", "reviewer", "auditor", "operator", "deployment", "agent"];
+export declare const RoleSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodEnum<{
+    agent: "agent";
+    reporter: "reporter";
+    implementer: "implementer";
+    reviewer: "reviewer";
+    auditor: "auditor";
+    operator: "operator";
+    deployment: "deployment";
+}>>;
+export type Role = (typeof ROLE_TOKENS)[number];
+/**
+ * Canonical ACTION vocabulary — POSITIVE actions only (see file header). Each
+ * is a thing an actor *does*; prohibition/obligation/permission is expressed
+ * via `deontic`, never by negating the action name.
+ */
+export declare const ACTION_TOKENS: readonly ["close-issue", "merge-pr", "self-merge", "auto-close-keyword", "implement", "mutate-universal-rule", "ratify-rule-change"];
+export declare const ActionSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodEnum<{
+    "close-issue": "close-issue";
+    "merge-pr": "merge-pr";
+    "self-merge": "self-merge";
+    "auto-close-keyword": "auto-close-keyword";
+    implement: "implement";
+    "mutate-universal-rule": "mutate-universal-rule";
+    "ratify-rule-change": "ratify-rule-change";
+}>>;
+export type Action = (typeof ACTION_TOKENS)[number];
+/**
+ * Canonical CONDITION vocabulary — the circumstance under which the norm
+ * applies. `always` is the unconditioned default. Conditions are exact-match
+ * keys in v1 (no subsumption — deferred to G3).
+ */
+export declare const CONDITION_TOKENS: readonly ["always", "after-merge", "without-non-author-approval", "on-foreign-reporter-issue"];
+export declare const ConditionSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodEnum<{
+    always: "always";
+    "after-merge": "after-merge";
+    "without-non-author-approval": "without-non-author-approval";
+    "on-foreign-reporter-issue": "on-foreign-reporter-issue";
+}>>;
+export type Condition = (typeof CONDITION_TOKENS)[number];
+/** The three deontic modalities. */
+export declare const DeonticSchema: z.ZodEnum<{
+    obligation: "obligation";
+    permission: "permission";
+    prohibition: "prohibition";
+}>;
+export type Deontic = z.infer<typeof DeonticSchema>;
+/** Which tier a norm belongs to (constitutional vs deployment-local). */
+export declare const NormTierSchema: z.ZodEnum<{
+    project: "project";
+    universal: "universal";
+}>;
+export type NormTier = z.infer<typeof NormTierSchema>;
+/**
+ * A single structured norm.
+ *
+ * `role` / `action` / `condition` are the three CANONICAL match-keys the
+ * conflict-checker groups on. `deontic` is the modality. `deadline` and
+ * `sanction` are optional descriptive fields (not used by the v1 checker —
+ * room for G3's temporal logic). `tier` + `provenance` record where the norm
+ * came from (the source rule / invariant), so a flagged conflict is traceable
+ * back to a human-readable rule.
+ */
+export declare const NormSchema: z.ZodObject<{
+    id: z.ZodString;
+    schema_version: z.ZodLiteral<"1.0">;
+    kind: z.ZodLiteral<"macf.norm">;
+    role: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodEnum<{
+        agent: "agent";
+        reporter: "reporter";
+        implementer: "implementer";
+        reviewer: "reviewer";
+        auditor: "auditor";
+        operator: "operator";
+        deployment: "deployment";
+    }>>;
+    deontic: z.ZodEnum<{
+        obligation: "obligation";
+        permission: "permission";
+        prohibition: "prohibition";
+    }>;
+    action: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodEnum<{
+        "close-issue": "close-issue";
+        "merge-pr": "merge-pr";
+        "self-merge": "self-merge";
+        "auto-close-keyword": "auto-close-keyword";
+        implement: "implement";
+        "mutate-universal-rule": "mutate-universal-rule";
+        "ratify-rule-change": "ratify-rule-change";
+    }>>;
+    condition: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodEnum<{
+        always: "always";
+        "after-merge": "after-merge";
+        "without-non-author-approval": "without-non-author-approval";
+        "on-foreign-reporter-issue": "on-foreign-reporter-issue";
+    }>>;
+    deadline: z.ZodOptional<z.ZodString>;
+    sanction: z.ZodOptional<z.ZodString>;
+    tier: z.ZodEnum<{
+        project: "project";
+        universal: "universal";
+    }>;
+    provenance: z.ZodString;
+}, z.core.$strip>;
+export type Norm = z.infer<typeof NormSchema>;
+/**
+ * A transition in the issue-lifecycle scene. `from`/`to` are state names;
+ * `roleGate` (optional) names the role permitted to drive the transition;
+ * `normRef` (optional) points at a `Norm.id` that governs it. Data-model
+ * only — no transition is *executed* anywhere; the runtime governor is the
+ * hooks + auditor.
+ */
+export declare const TransitionSchema: z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+    roleGate: z.ZodOptional<z.ZodString>;
+    normRef: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Transition = z.infer<typeof TransitionSchema>;
+/**
+ * The issue-lifecycle scene: the set of states an issue moves through and the
+ * legal transitions between them, mirroring `coordination.md` §Issue
+ * Lifecycle + the agent-identity label table (open → in-progress → in-review
+ * → closed, with a blocked side-state). DATA ONLY — see file header.
+ */
+export declare const SceneSchema: z.ZodObject<{
+    id: z.ZodString;
+    schema_version: z.ZodLiteral<"1.0">;
+    kind: z.ZodLiteral<"macf.scene">;
+    states: z.ZodArray<z.ZodString>;
+    transitions: z.ZodArray<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+        roleGate: z.ZodOptional<z.ZodString>;
+        normRef: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Scene = z.infer<typeof SceneSchema>;
+/** The kind of deontic clash the checker found. */
+export declare const ConflictTypeSchema: z.ZodEnum<{
+    "obligation-vs-prohibition": "obligation-vs-prohibition";
+    "permission-vs-prohibition": "permission-vs-prohibition";
+}>;
+export type ConflictType = z.infer<typeof ConflictTypeSchema>;
+/** A detected conflict: the two clashing norms + the clash type. */
+export interface NormConflict {
+    readonly a: Norm;
+    readonly b: Norm;
+    readonly type: ConflictType;
+}
+/** A non-blocking advisory: same-key duplicate obligations (redundant rule). */
+export interface NormWarning {
+    readonly a: Norm;
+    readonly b: Norm;
+    readonly kind: 'duplicate-obligation';
+}
+/** The result of a conflict-check pass. */
+export interface ConflictCheckResult {
+    readonly conflicts: readonly NormConflict[];
+    readonly warnings: readonly NormWarning[];
+}
+/**
+ * Detect deontic conflicts among a set of norms.
+ *
+ * Groups norms by their already-canonical `(role, action, condition)` triple,
+ * then within each group compares every pair:
+ *   - opposite-modality clashes (obligation/prohibition, permission/prohibition)
+ *     are returned as CONFLICTS;
+ *   - duplicate obligations on the same key are returned as non-blocking
+ *     WARNINGS (a likely-redundant rule, not a contradiction).
+ *
+ * Because the keys are canonical (the schema normalized them), two norms that
+ * conflict but were spelled differently on input (`after_merge` vs
+ * `after-merge`) land in the SAME group and are correctly flagged — that is
+ * the whole point of the controlled vocabulary.
+ *
+ * v1 is exact-token grouping only. Condition subsumption, temporal/deadline
+ * reasoning, and role-hierarchy inheritance are DEFERRED to G3 (macf#505).
+ */
+export declare function detectNormConflicts(norms: readonly Norm[]): ConflictCheckResult;
+//# sourceMappingURL=norm.d.ts.map

package/dist/norm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"norm.d.ts","sourceRoot":"","sources":["../src/norm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,oEAAoE;AACpE,eAAO,MAAM,mBAAmB,EAAG,KAAc,CAAC;AAElD,0EAA0E;AAC1E,eAAO,MAAM,SAAS,EAAG,WAAoB,CAAC;AAE9C;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAKhD;AAUD;;;GAGG;AACH,eAAO,MAAM,WAAW,gGAQd,CAAC;AACX,eAAO,MAAM,UAAU;;;;;;;;GAAiC,CAAC;AACzD,MAAM,MAAM,IAAI,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,aAAa,sIAQhB,CAAC;AACX,eAAO,MAAM,YAAY;;;;;;;;GAAmC,CAAC;AAC7D,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,gGAKnB,CAAC;AACX,eAAO,MAAM,eAAe;;;;;GAAsC,CAAC;AACnE,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,oCAAoC;AACpC,eAAO,MAAM,aAAa;;;;EAAsD,CAAC;AACjF,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD,yEAAyE;AACzE,eAAO,MAAM,cAAc;;;EAAmC,CAAC;AAC/D,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAYrB,CAAC;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAE9C;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;;;;;iBAK3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;iBAMtB,CAAC;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEhD,mDAAmD;AACnD,eAAO,MAAM,kBAAkB;;;EAG7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC;IACjB,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC;IACjB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;CAC7B;AAED,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC;IACjB,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC;IACjB,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;CACvC;AAED,2CAA2C;AAC3C,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,SAAS,YAAY,EAAE,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;CAC3C;AAyBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,mBAAmB,CA4B/E"}

package/dist/norm.js

@@ -0,0 +1,252 @@
+/**
+ * Versioned structured-norm (Moise-style) representation + deontic
+ * conflict-checker (groundnuty/macf#504, DR-026 G2 — PR-1).
+ *
+ * This module gives the coordination protocol a *machine-checkable* form for
+ * its norms. A "norm" is a deontic statement — an obligation, permission, or
+ * prohibition — bound to a `(role, action, condition)` triple. G3's SECP
+ * invariant-validator (macf#505) consumes this representation to mechanically
+ * check that a proposed rule change never contradicts a protected invariant.
+ *
+ * --------------------------------------------------------------------------
+ * G2 MODELS, IT DOES NOT ENFORCE.
+ * --------------------------------------------------------------------------
+ * This is a *data model* only. The runtime governor is the existing set of
+ * `check-*.sh` PreToolUse/PostToolUse hooks plus the DR-026 auditor — they
+ * are what actually block/warn at tool-call time. `SceneSchema` below models
+ * the issue-lifecycle scene as data (states + transitions); it carries NO
+ * enforcement code. Nothing here runs at coordination time.
+ *
+ * --------------------------------------------------------------------------
+ * CONTROLLED VOCABULARIES — the load-bearing guardrail.
+ * --------------------------------------------------------------------------
+ * The conflict-checker matches norms on three keys: `role`, `action`,
+ * `condition`. If two genuinely-conflicting norms are spelled differently
+ * (`after_merge` vs `after-merge`), a naive checker silently fails to match
+ * them — producing FALSE CONFIDENCE, which is worse than no checker at all.
+ *
+ * To close that silent-miss, every match-key is a CLOSED Zod enum over a
+ * canonical token set, and `normalizeToken` is applied to inputs first
+ * (lowercase, collapse runs of `_`/whitespace/`-` to a single `-`). An
+ * unknown token after normalization is REJECTED by the schema, forcing a
+ * deliberate vocabulary extension rather than an accidental synonym.
+ *
+ * --------------------------------------------------------------------------
+ * POSITIVE-ACTION CONVENTION.
+ * --------------------------------------------------------------------------
+ * The `Action` enum carries ONLY positive actions (`self-merge`,
+ * `close-issue`, …) — NEVER negated forms (`not-self-merge`). Negation lives
+ * exclusively in the `deontic` field. This is deliberate: if negated actions
+ * were allowed, a `prohibition(merge-pr)` could be silently dodged by
+ * re-expressing it as `obligation(not-merge-pr)` — the same constraint under
+ * a key the conflict-checker would never group together. Keeping actions
+ * positive means a clash on a constraint is always visible on one shared key.
+ *
+ * --------------------------------------------------------------------------
+ * DEONTIC-CONFLICT MATRIX (within one (role, action, condition) group).
+ * --------------------------------------------------------------------------
+ *   obligation  ∧ prohibition  → CONFLICT  ("must" vs "must not")
+ *   permission  ∧ prohibition  → CONFLICT  ("may"  vs "must not")
+ *   obligation  ∧ permission   → consistent (obligation ⊨ permission)
+ * Same deontic on the same key is not a logical conflict; duplicate
+ * obligations get a NON-BLOCKING warning (likely a redundant rule).
+ *
+ * v1 SCOPE: matching is exact-token on the canonical triple. Condition
+ * subsumption (one condition implies another), temporal/deadline logic, and
+ * role-hierarchy inheritance are DEFERRED to the G3 increment (macf#505).
+ */
+import { z } from 'zod';
+/** Current norm schema version. Bump on a breaking shape change. */
+export const NORM_SCHEMA_VERSION = '1.0';
+/** Stable type-tag distinguishing norm records on a multi-kind ledger. */
+export const NORM_KIND = 'macf.norm';
+/**
+ * Canonicalize a vocabulary token: lowercase, then collapse any run of
+ * underscores / whitespace / hyphens into a single hyphen, and trim leading
+ * and trailing hyphens. This is what makes `after_merge`, `after merge`,
+ * `After-Merge`, and `after--merge` all map to the ONE canonical token
+ * `after-merge`. Applied to every match-key before enum validation so the
+ * enum only ever sees canonical forms.
+ */
+export function normalizeToken(s) {
+    return s
+        .toLowerCase()
+        .replace(/[\s_-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * A Zod preprocessor that normalizes the input token before the wrapped enum
+ * validates it. Non-string inputs pass through untouched so the enum produces
+ * its normal type error.
+ */
+const canonical = (schema) => z.preprocess((v) => (typeof v === 'string' ? normalizeToken(v) : v), schema);
+/**
+ * Canonical ROLE vocabulary — the coordination actors a norm can bind to.
+ * Closed set: an unknown role is rejected (extend deliberately).
+ */
+export const ROLE_TOKENS = [
+    'reporter',
+    'implementer',
+    'reviewer',
+    'auditor',
+    'operator',
+    'deployment',
+    'agent',
+];
+export const RoleSchema = canonical(z.enum(ROLE_TOKENS));
+/**
+ * Canonical ACTION vocabulary — POSITIVE actions only (see file header). Each
+ * is a thing an actor *does*; prohibition/obligation/permission is expressed
+ * via `deontic`, never by negating the action name.
+ */
+export const ACTION_TOKENS = [
+    'close-issue',
+    'merge-pr',
+    'self-merge',
+    'auto-close-keyword',
+    'implement',
+    'mutate-universal-rule',
+    'ratify-rule-change',
+];
+export const ActionSchema = canonical(z.enum(ACTION_TOKENS));
+/**
+ * Canonical CONDITION vocabulary — the circumstance under which the norm
+ * applies. `always` is the unconditioned default. Conditions are exact-match
+ * keys in v1 (no subsumption — deferred to G3).
+ */
+export const CONDITION_TOKENS = [
+    'always',
+    'after-merge',
+    'without-non-author-approval',
+    'on-foreign-reporter-issue',
+];
+export const ConditionSchema = canonical(z.enum(CONDITION_TOKENS));
+/** The three deontic modalities. */
+export const DeonticSchema = z.enum(['obligation', 'permission', 'prohibition']);
+/** Which tier a norm belongs to (constitutional vs deployment-local). */
+export const NormTierSchema = z.enum(['universal', 'project']);
+/**
+ * A single structured norm.
+ *
+ * `role` / `action` / `condition` are the three CANONICAL match-keys the
+ * conflict-checker groups on. `deontic` is the modality. `deadline` and
+ * `sanction` are optional descriptive fields (not used by the v1 checker —
+ * room for G3's temporal logic). `tier` + `provenance` record where the norm
+ * came from (the source rule / invariant), so a flagged conflict is traceable
+ * back to a human-readable rule.
+ */
+export const NormSchema = z.object({
+    id: z.string(),
+    schema_version: z.literal(NORM_SCHEMA_VERSION),
+    kind: z.literal(NORM_KIND),
+    role: RoleSchema,
+    deontic: DeonticSchema,
+    action: ActionSchema,
+    condition: ConditionSchema,
+    deadline: z.string().optional(),
+    sanction: z.string().optional(),
+    tier: NormTierSchema,
+    provenance: z.string(),
+});
+/**
+ * A transition in the issue-lifecycle scene. `from`/`to` are state names;
+ * `roleGate` (optional) names the role permitted to drive the transition;
+ * `normRef` (optional) points at a `Norm.id` that governs it. Data-model
+ * only — no transition is *executed* anywhere; the runtime governor is the
+ * hooks + auditor.
+ */
+export const TransitionSchema = z.object({
+    from: z.string(),
+    to: z.string(),
+    roleGate: z.string().optional(),
+    normRef: z.string().optional(),
+});
+/**
+ * The issue-lifecycle scene: the set of states an issue moves through and the
+ * legal transitions between them, mirroring `coordination.md` §Issue
+ * Lifecycle + the agent-identity label table (open → in-progress → in-review
+ * → closed, with a blocked side-state). DATA ONLY — see file header.
+ */
+export const SceneSchema = z.object({
+    id: z.string(),
+    schema_version: z.literal(NORM_SCHEMA_VERSION),
+    kind: z.literal('macf.scene'),
+    states: z.array(z.string()),
+    transitions: z.array(TransitionSchema),
+});
+/** The kind of deontic clash the checker found. */
+export const ConflictTypeSchema = z.enum([
+    'obligation-vs-prohibition',
+    'permission-vs-prohibition',
+]);
+/** The canonical group key for a norm: its (role, action, condition) triple. */
+function groupKey(n) {
+    // Values are already canonical (validated by the enums), so JSON-joining is
+    // a stable, collision-free key for grouping.
+    return JSON.stringify([n.role, n.action, n.condition]);
+}
+/**
+ * Is this an actual deontic conflict per the matrix? Returns the conflict
+ * type, or `null` if the pair is consistent.
+ *
+ *   obligation ∧ prohibition → conflict
+ *   permission ∧ prohibition → conflict
+ *   obligation ∧ permission  → consistent (obligation entails permission)
+ *   same modality            → consistent (handled as a warning elsewhere)
+ */
+function clashType(d1, d2) {
+    const pair = new Set([d1, d2]);
+    if (pair.has('prohibition') && pair.has('obligation'))
+        return 'obligation-vs-prohibition';
+    if (pair.has('prohibition') && pair.has('permission'))
+        return 'permission-vs-prohibition';
+    return null;
+}
+/**
+ * Detect deontic conflicts among a set of norms.
+ *
+ * Groups norms by their already-canonical `(role, action, condition)` triple,
+ * then within each group compares every pair:
+ *   - opposite-modality clashes (obligation/prohibition, permission/prohibition)
+ *     are returned as CONFLICTS;
+ *   - duplicate obligations on the same key are returned as non-blocking
+ *     WARNINGS (a likely-redundant rule, not a contradiction).
+ *
+ * Because the keys are canonical (the schema normalized them), two norms that
+ * conflict but were spelled differently on input (`after_merge` vs
+ * `after-merge`) land in the SAME group and are correctly flagged — that is
+ * the whole point of the controlled vocabulary.
+ *
+ * v1 is exact-token grouping only. Condition subsumption, temporal/deadline
+ * reasoning, and role-hierarchy inheritance are DEFERRED to G3 (macf#505).
+ */
+export function detectNormConflicts(norms) {
+    const groups = new Map();
+    for (const n of norms) {
+        const key = groupKey(n);
+        const bucket = groups.get(key);
+        if (bucket)
+            bucket.push(n);
+        else
+            groups.set(key, [n]);
+    }
+    const conflicts = [];
+    const warnings = [];
+    for (const bucket of groups.values()) {
+        for (let i = 0; i < bucket.length; i++) {
+            for (let j = i + 1; j < bucket.length; j++) {
+                const a = bucket[i];
+                const b = bucket[j];
+                const type = clashType(a.deontic, b.deontic);
+                if (type) {
+                    conflicts.push({ a, b, type });
+                }
+                else if (a.deontic === 'obligation' && b.deontic === 'obligation') {
+                    warnings.push({ a, b, kind: 'duplicate-obligation' });
+                }
+            }
+        }
+    }
+    return { conflicts, warnings };
+}
+//# sourceMappingURL=norm.js.map

package/dist/norm.js.map

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

package/dist/protected-invariant-norms.d.ts

@@ -0,0 +1,37 @@
+import type { Norm } from './norm.js';
+import { z } from 'zod';
+/**
+ * A protected invariant that is a structural PROPERTY rather than a deontic
+ * norm. `statement` restates the guarantee; `whyNotANorm` records why it
+ * resists the `(role, action, condition)` shape; `enforcement` names the
+ * mechanism that actually guarantees it at runtime.
+ */
+export declare const StructuralInvariantSchema: z.ZodObject<{
+    id: z.ZodString;
+    statement: z.ZodString;
+    whyNotANorm: z.ZodString;
+    enforcement: z.ZodString;
+}, z.core.$strip>;
+export type StructuralInvariant = z.infer<typeof StructuralInvariantSchema>;
+/**
+ * The norm-expressible protected invariants. Each `provenance` points back at
+ * the numbered entry in `design/protected-invariants.md`.
+ */
+export declare const PROTECTED_INVARIANT_NORMS: readonly Norm[];
+/**
+ * The structural-property protected invariants. These are guarantees the
+ * conflict-checker does NOT reason over — they are enforced by mechanisms, not
+ * by deontic logic. Tagged here so the full set of 10 is accounted for and G3
+ * knows to route them to the structural-enforcement check, not the norm
+ * conflict-check.
+ */
+export declare const PROTECTED_STRUCTURAL_INVARIANTS: readonly StructuralInvariant[];
+/**
+ * Short machine-readable taxonomy note: which of the 10 invariants became a
+ * norm vs a structural property. Mirrors `design/structured-norms.md`.
+ */
+export declare const PROTECTED_INVARIANT_TAXONOMY: {
+    readonly normExpressible: readonly [1, 3, 5, 8, 9, 10];
+    readonly structural: readonly [2, 4, 6, 7];
+};
+//# sourceMappingURL=protected-invariant-norms.d.ts.map

package/dist/protected-invariant-norms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protected-invariant-norms.d.ts","sourceRoot":"","sources":["../src/protected-invariant-norms.ts"],"names":[],"mappings":"AA8CA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;;;;;iBAKpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAW5E;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,IAAI,EAuFpD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,+BAA+B,EAAE,SAAS,mBAAmB,EAqCzE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,4BAA4B;;;CAG/B,CAAC"}