jingu-protocol 0.1.0

package/README.md

@@ -0,0 +1,162 @@
+# jingu-protocol
+
+Shared protocol types for the [Jingu](https://github.com/ylu999/jingu-core) system.
+
+Contains the **Reasoning Provenance Protocol (RPP)** — a per-call cognitive audit contract that requires every AI reasoning step to be traceable to evidence, rules, or methods before any tool or action is allowed to execute.
+
+```
+Every claim an AI makes must be backed by a reference.
+If you can't trace it, you can't trust it.
+```
+
+---
+
+## What is RPP?
+
+RPP is a structured audit record that an AI agent must produce alongside any action it takes. It enforces four cognitive stages before execution:
+
+```
+interpretation → reasoning → decision → action → response
+```
+
+Each stage must:
+- Have non-empty content
+- Cite at least one reference (evidence, rule, or method)
+- The decision stage must cite a rule or method (not just evidence)
+- The response content must be traceable to prior step content
+
+A `pre_tool_use` hook validates the RPP block before any tool runs. Missing or invalid RPP blocks the execution.
+
+---
+
+## Install
+
+```bash
+npm install jingu-protocol
+```
+
+---
+
+## Quick start
+
+```typescript
+import { validateRPP } from "jingu-protocol"
+import type { RPPRecord } from "jingu-protocol"
+
+const record: RPPRecord = {
+  call_id: "call-001",
+  steps: [
+    {
+      stage: "interpretation",
+      content: ["User wants to read file foo.ts"],
+      references: [{ type: "evidence", source: "user_input", locator: "message.current", supports: "user asked to read foo.ts" }],
+    },
+    {
+      stage: "reasoning",
+      content: ["foo.ts likely contains the type definition we need"],
+      references: [{ type: "method", method_id: "DBG-001", supports: "read before write — inspect file before modifying" }],
+    },
+    {
+      stage: "decision",
+      content: ["Read foo.ts to confirm type shape before editing"],
+      references: [{ type: "rule", rule_id: "RUL-002", supports: "cite evidence for every claim before acting" }],
+    },
+    {
+      stage: "action",
+      content: ["Read foo.ts"],
+      references: [{ type: "evidence", source: "file", locator: "src/foo.ts", supports: "target file for the read action" }],
+    },
+  ],
+  response: {
+    content: ["Read foo.ts to confirm type shape"],
+    references: [{ type: "derived", supports: "action step states: read foo.ts" }],
+  },
+}
+
+const result = validateRPP(record)
+// result.overall_status: "valid" | "weakly_supported" | "invalid"
+// result.failures: RPPFailure[]   — hard failures (block execution)
+// result.warnings: RPPFailure[]   — soft failures (flagged but allowed)
+```
+
+---
+
+## Validation rules
+
+### Hard failures — block execution
+
+| Code | What it catches |
+|------|----------------|
+| `MISSING_STAGE` | One of the 4 required stages (interpretation, reasoning, decision, action) is absent |
+| `EMPTY_CONTENT` | A stage has no content entries |
+| `NO_REFERENCES` | A stage has no references |
+| `UNJUSTIFIED_DECISION` | Decision stage has only evidence refs — must have at least one rule or method |
+| `UNTRACEABLE_RESPONSE` | Response content cannot be traced back to any prior step |
+| `INVALID_REFERENCE` | A rule_id or method_id is malformed, or an evidence ref has empty source/locator |
+
+### Soft failures — warnings only
+
+| Code | What it catches |
+|------|----------------|
+| `SUPPORTS_TOO_VAGUE` | A reference's `supports` field is under 10 characters |
+| `INFERENCE_AS_FACT` | Reasoning stage uses certainty language without an evidence reference |
+| `METHOD_NOT_ACTUALLY_USED` | A method_id is cited but the method's logic is not reflected in the content |
+| `CIRCULAR_REFERENCE` | Two references mutually cite each other with no external grounding |
+| `ACTION_SCOPE_VIOLATION` | Action proposes more than what the decision stage authorized |
+
+---
+
+## Reference types
+
+```typescript
+type EvidenceRef = {
+  type: "evidence"
+  source: string      // "user_input" | "file" | "log" | "test_output" | "tool_result"
+  locator: string     // file path with optional :line, log line range, etc.
+  supports: string    // which specific claim this evidence supports
+}
+
+type RuleRef = {
+  type: "rule"
+  rule_id: string     // must match /^[A-Z]+-\d+$/ — e.g. "RUL-001"
+  supports: string
+}
+
+type MethodRef = {
+  type: "method"
+  method_id: string   // must match /^[A-Z]+-\d+$/ — e.g. "RCA-001"
+  supports: string
+}
+```
+
+---
+
+## Exports
+
+```typescript
+// Types
+export type { RPPRecord, RPPFailure, RPPFailureCode, RPPValidationResult }
+export type { EvidenceRef, RuleRef, MethodRef, Reference }
+export type { CognitiveStep, ResponseStep }
+export type { RPPFailureDescription }
+
+// Functions
+export { validateRPP }
+export { isHardFailure }
+export { RPP_FAILURE_DESCRIPTIONS }
+```
+
+---
+
+## Who uses this
+
+| Package | Role |
+|---------|------|
+| [`jingu-trust-gate`](https://github.com/ylu999/jingu-trust-gate) | Runs `validateRPP` as a `pre_tool_use` hook — blocks tool execution if RPP is missing or invalid |
+| [`jingu-policy-core`](https://github.com/ylu999/jingu-policy-core) | Re-exports all RPP types for consumers that import from `jingu-policy-core` |
+
+---
+
+## License
+
+MIT

package/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+export type { EvidenceRef, RuleRef, MethodRef, Reference, CognitiveStep, ResponseStep, RPPRecord, RPPFailureCode, RPPFailure, RPPValidationResult, } from "./rpp/rpp.types.js";
+export type { RPPFailureDescription } from "./rpp/rpp.failures.js";
+export { RPP_FAILURE_DESCRIPTIONS, isHardFailure } from "./rpp/rpp.failures.js";
+export { validateRPP } from "./rpp/rpp.validate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAEA,YAAY,EACV,WAAW,EACX,OAAO,EACP,SAAS,EACT,SAAS,EACT,aAAa,EACb,YAAY,EACZ,SAAS,EACT,cAAc,EACd,UAAU,EACV,mBAAmB,GACpB,MAAM,oBAAoB,CAAA;AAE3B,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAClE,OAAO,EAAE,wBAAwB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAE/E,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/src/index.js

@@ -0,0 +1,4 @@
+// src/index.ts — jingu-protocol public API
+export { RPP_FAILURE_DESCRIPTIONS, isHardFailure } from "./rpp/rpp.failures.js";
+export { validateRPP } from "./rpp/rpp.validate.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAgB3C,OAAO,EAAE,wBAAwB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAE/E,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/src/rpp/rpp.failures.d.ts

@@ -0,0 +1,9 @@
+import { RPPFailureCode } from "./rpp.types.js";
+export type RPPFailureDescription = {
+    severity: "error" | "warning";
+    description: string;
+    example: string;
+};
+export declare const RPP_FAILURE_DESCRIPTIONS: Record<RPPFailureCode, RPPFailureDescription>;
+export declare function isHardFailure(code: RPPFailureCode): boolean;
+//# sourceMappingURL=rpp.failures.d.ts.map

package/dist/src/rpp/rpp.failures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpp.failures.d.ts","sourceRoot":"","sources":["../../../src/rpp/rpp.failures.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAE/C,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7B,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,cAAc,EAAE,qBAAqB,CAgElF,CAAA;AAWD,wBAAgB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAE3D"}

package/dist/src/rpp/rpp.failures.js

@@ -0,0 +1,77 @@
+// src/rpp/rpp.failures.ts
+export const RPP_FAILURE_DESCRIPTIONS = {
+    // Hard failures (severity: "error") — block execution
+    MISSING_STAGE: {
+        severity: "error",
+        description: "A required cognitive stage (interpretation, reasoning, decision, or action) is absent from the RPP record.",
+        example: "RPP record has steps for interpretation and decision but omits the reasoning stage entirely.",
+    },
+    EMPTY_CONTENT: {
+        severity: "error",
+        description: "A stage or response step has an empty content array or all content entries are blank strings.",
+        example: "The decision stage has content: [] with no entries explaining what was decided.",
+    },
+    NO_REFERENCES: {
+        severity: "error",
+        description: "A stage or response step that requires references has none, making the output ungrounded.",
+        example: "The response step cites no evidence or rules despite making factual claims.",
+    },
+    UNTRACEABLE_RESPONSE: {
+        severity: "error",
+        description: "The final response cannot be traced back to any step in the cognitive chain — no references link response to prior reasoning.",
+        example: "Response says 'use method X' but no reasoning or decision step mentions method X.",
+    },
+    UNJUSTIFIED_DECISION: {
+        severity: "error",
+        description: "A decision stage has no supporting rule or evidence reference to justify why this decision was made.",
+        example: "Decision stage selects option B but provides no rule_id or evidence reference explaining the choice.",
+    },
+    INVALID_REFERENCE: {
+        severity: "error",
+        description: "A reference is structurally malformed or points to a non-existent source, rule, or method.",
+        example: "A RuleRef has rule_id: '' (empty string) or an EvidenceRef has a locator that does not match any known document.",
+    },
+    // Soft failures (severity: "warning") — flagged but do not block
+    UNSUPPORTED_CLAIM: {
+        severity: "warning",
+        description: "A content entry makes a factual claim that has no corresponding reference supporting it.",
+        example: "Reasoning stage states 'This pattern is always inefficient' but no evidence reference backs that claim.",
+    },
+    INFERENCE_AS_FACT: {
+        severity: "warning",
+        description: "An inference or assumption is stated as established fact without acknowledging uncertainty.",
+        example: "Content says 'The user intends to deploy to production' without marking it as an inference or listing it in uncertainties.",
+    },
+    SUPPORTS_TOO_VAGUE: {
+        severity: "warning",
+        description: "A reference's 'supports' field is too generic to meaningfully trace which claim it backs.",
+        example: "EvidenceRef has supports: 'general context' instead of specifying which particular claim it supports.",
+    },
+    METHOD_NOT_ACTUALLY_USED: {
+        severity: "warning",
+        description: "A method_ref is declared in a stage but the method's logic is not reflected in the stage's content.",
+        example: "Stage declares method_ref for 'cost-benefit-analysis' but the content shows no cost or benefit comparison.",
+    },
+    CIRCULAR_REFERENCE: {
+        severity: "warning",
+        description: "Two or more references form a cycle where each claims to support the other with no external grounding.",
+        example: "Step A references step B as evidence, and step B references step A as its justification.",
+    },
+    ACTION_SCOPE_VIOLATION: {
+        severity: "warning",
+        description: "An action step proposes actions that exceed the scope authorized by the preceding decision stage.",
+        example: "Decision stage authorizes 'update config file' but action stage also proposes 'delete the database'.",
+    },
+};
+const HARD_FAILURE_CODES = new Set([
+    "MISSING_STAGE",
+    "EMPTY_CONTENT",
+    "NO_REFERENCES",
+    "UNTRACEABLE_RESPONSE",
+    "UNJUSTIFIED_DECISION",
+    "INVALID_REFERENCE",
+]);
+export function isHardFailure(code) {
+    return HARD_FAILURE_CODES.has(code);
+}
+//# sourceMappingURL=rpp.failures.js.map

package/dist/src/rpp/rpp.failures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpp.failures.js","sourceRoot":"","sources":["../../../src/rpp/rpp.failures.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAU1B,MAAM,CAAC,MAAM,wBAAwB,GAAkD;IACrF,sDAAsD;IACtD,aAAa,EAAE;QACb,QAAQ,EAAE,OAAO;QACjB,WAAW,EAAE,4GAA4G;QACzH,OAAO,EAAE,8FAA8F;KACxG;IACD,aAAa,EAAE;QACb,QAAQ,EAAE,OAAO;QACjB,WAAW,EAAE,+FAA+F;QAC5G,OAAO,EAAE,iFAAiF;KAC3F;IACD,aAAa,EAAE;QACb,QAAQ,EAAE,OAAO;QACjB,WAAW,EAAE,2FAA2F;QACxG,OAAO,EAAE,6EAA6E;KACvF;IACD,oBAAoB,EAAE;QACpB,QAAQ,EAAE,OAAO;QACjB,WAAW,EAAE,+HAA+H;QAC5I,OAAO,EAAE,mFAAmF;KAC7F;IACD,oBAAoB,EAAE;QACpB,QAAQ,EAAE,OAAO;QACjB,WAAW,EAAE,sGAAsG;QACnH,OAAO,EAAE,sGAAsG;KAChH;IACD,iBAAiB,EAAE;QACjB,QAAQ,EAAE,OAAO;QACjB,WAAW,EAAE,4FAA4F;QACzG,OAAO,EAAE,kHAAkH;KAC5H;IAED,iEAAiE;IACjE,iBAAiB,EAAE;QACjB,QAAQ,EAAE,SAAS;QACnB,WAAW,EAAE,0FAA0F;QACvG,OAAO,EAAE,yGAAyG;KACnH;IACD,iBAAiB,EAAE;QACjB,QAAQ,EAAE,SAAS;QACnB,WAAW,EAAE,6FAA6F;QAC1G,OAAO,EAAE,4HAA4H;KACtI;IACD,kBAAkB,EAAE;QAClB,QAAQ,EAAE,SAAS;QACnB,WAAW,EAAE,2FAA2F;QACxG,OAAO,EAAE,uGAAuG;KACjH;IACD,wBAAwB,EAAE;QACxB,QAAQ,EAAE,SAAS;QACnB,WAAW,EAAE,qGAAqG;QAClH,OAAO,EAAE,4GAA4G;KACtH;IACD,kBAAkB,EAAE;QAClB,QAAQ,EAAE,SAAS;QACnB,WAAW,EAAE,wGAAwG;QACrH,OAAO,EAAE,0FAA0F;KACpG;IACD,sBAAsB,EAAE;QACtB,QAAQ,EAAE,SAAS;QACnB,WAAW,EAAE,mGAAmG;QAChH,OAAO,EAAE,sGAAsG;KAChH;CACF,CAAA;AAED,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAiB;IACjD,eAAe;IACf,eAAe;IACf,eAAe;IACf,sBAAsB;IACtB,sBAAsB;IACtB,mBAAmB;CACpB,CAAC,CAAA;AAEF,MAAM,UAAU,aAAa,CAAC,IAAoB;IAChD,OAAO,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AACrC,CAAC"}

package/dist/src/rpp/rpp.types.d.ts

@@ -0,0 +1,47 @@
+export type EvidenceRef = {
+    type: "evidence";
+    source: string;
+    locator: string;
+    supports: string;
+};
+export type RuleRef = {
+    type: "rule";
+    rule_id: string;
+    supports: string;
+};
+export type MethodRef = {
+    type: "method";
+    method_id: string;
+    supports: string;
+};
+export type Reference = EvidenceRef | RuleRef | MethodRef;
+export type CognitiveStep = {
+    stage: "interpretation" | "reasoning" | "decision" | "action";
+    content: string[];
+    references: Reference[];
+    method_refs?: MethodRef[];
+    uncertainties?: string[];
+};
+export type ResponseStep = {
+    content: string[];
+    references: Reference[];
+};
+export type RPPRecord = {
+    call_id: string;
+    session_id?: string;
+    call_sequence?: number;
+    steps: CognitiveStep[];
+    response: ResponseStep;
+};
+export type RPPFailureCode = "MISSING_STAGE" | "EMPTY_CONTENT" | "NO_REFERENCES" | "UNSUPPORTED_CLAIM" | "INFERENCE_AS_FACT" | "UNTRACEABLE_RESPONSE" | "UNJUSTIFIED_DECISION" | "ACTION_SCOPE_VIOLATION" | "METHOD_NOT_ACTUALLY_USED" | "INVALID_REFERENCE" | "SUPPORTS_TOO_VAGUE" | "CIRCULAR_REFERENCE";
+export type RPPFailure = {
+    code: RPPFailureCode;
+    stage?: CognitiveStep["stage"] | "response";
+    detail: string;
+};
+export type RPPValidationResult = {
+    overall_status: "valid" | "weakly_supported" | "invalid";
+    failures: RPPFailure[];
+    warnings: RPPFailure[];
+};
+//# sourceMappingURL=rpp.types.d.ts.map

package/dist/src/rpp/rpp.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpp.types.d.ts","sourceRoot":"","sources":["../../../src/rpp/rpp.types.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,UAAU,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,QAAQ,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,OAAO,GAAG,SAAS,CAAA;AAEzD,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,gBAAgB,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,CAAA;IAC7D,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,UAAU,EAAE,SAAS,EAAE,CAAA;IACvB,WAAW,CAAC,EAAE,SAAS,EAAE,CAAA;IACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,UAAU,EAAE,SAAS,EAAE,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,KAAK,EAAE,aAAa,EAAE,CAAA;IACtB,QAAQ,EAAE,YAAY,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,cAAc,GACtB,eAAe,GACf,eAAe,GACf,eAAe,GACf,mBAAmB,GACnB,mBAAmB,GACnB,sBAAsB,GACtB,sBAAsB,GACtB,wBAAwB,GACxB,0BAA0B,GAC1B,mBAAmB,GACnB,oBAAoB,GACpB,oBAAoB,CAAA;AAExB,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,cAAc,CAAA;IACpB,KAAK,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,UAAU,CAAA;IAC3C,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,cAAc,EAAE,OAAO,GAAG,kBAAkB,GAAG,SAAS,CAAA;IACxD,QAAQ,EAAE,UAAU,EAAE,CAAA;IACtB,QAAQ,EAAE,UAAU,EAAE,CAAA;CACvB,CAAA"}

package/dist/src/rpp/rpp.types.js

@@ -0,0 +1,3 @@
+// src/rpp/rpp.types.ts
+export {};
+//# sourceMappingURL=rpp.types.js.map

package/dist/src/rpp/rpp.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpp.types.js","sourceRoot":"","sources":["../../../src/rpp/rpp.types.ts"],"names":[],"mappings":"AAAA,uBAAuB"}

package/dist/src/rpp/rpp.validate.d.ts

@@ -0,0 +1,3 @@
+import { RPPRecord, RPPValidationResult } from "./rpp.types.js";
+export declare function validateRPP(record: RPPRecord): RPPValidationResult;
+//# sourceMappingURL=rpp.validate.d.ts.map

package/dist/src/rpp/rpp.validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpp.validate.d.ts","sourceRoot":"","sources":["../../../src/rpp/rpp.validate.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAc,mBAAmB,EAA4B,MAAM,gBAAgB,CAAA;AAuErG,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,GAAG,mBAAmB,CAkIlE"}

package/dist/src/rpp/rpp.validate.js

@@ -0,0 +1,186 @@
+// src/rpp/rpp.validate.ts
+import { isHardFailure } from "./rpp.failures.js";
+const REQUIRED_STAGES = [
+    "interpretation",
+    "reasoning",
+    "decision",
+    "action",
+];
+const RULE_METHOD_ID_PATTERN = /^[A-Z]+-\d+$/;
+const CERTAINTY_WORDS = [
+    "is definitely",
+    "always",
+    "never",
+    "must be",
+    "certainly",
+];
+function validateReference(ref, stage) {
+    if (ref.type === "rule") {
+        if (!RULE_METHOD_ID_PATTERN.test(ref.rule_id)) {
+            return {
+                code: "INVALID_REFERENCE",
+                stage,
+                detail: `RuleRef has invalid rule_id: "${ref.rule_id}". Must match /^[A-Z]+-\\d+$/.`,
+            };
+        }
+    }
+    else if (ref.type === "method") {
+        if (!RULE_METHOD_ID_PATTERN.test(ref.method_id)) {
+            return {
+                code: "INVALID_REFERENCE",
+                stage,
+                detail: `MethodRef has invalid method_id: "${ref.method_id}". Must match /^[A-Z]+-\\d+$/.`,
+            };
+        }
+    }
+    else if (ref.type === "evidence") {
+        if (!ref.source || typeof ref.source !== "string" || ref.source.trim() === "") {
+            return {
+                code: "INVALID_REFERENCE",
+                stage,
+                detail: `EvidenceRef has empty or missing 'source' field.`,
+            };
+        }
+        if (!ref.locator || typeof ref.locator !== "string" || ref.locator.trim() === "") {
+            return {
+                code: "INVALID_REFERENCE",
+                stage,
+                detail: `EvidenceRef has empty or missing 'locator' field.`,
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Extract the first noun phrase from a string (min 3 chars).
+ * Simple heuristic: take the first word of length >= 3.
+ */
+function extractFirstKeyPhrase(text) {
+    const words = text.split(/\s+/);
+    for (const word of words) {
+        const cleaned = word.replace(/[^a-zA-Z0-9]/g, "");
+        if (cleaned.length >= 3) {
+            return cleaned.toLowerCase();
+        }
+    }
+    return null;
+}
+export function validateRPP(record) {
+    const allIssues = [];
+    // --- Check 1: MISSING_STAGE ---
+    const presentStages = new Set(record.steps.map((s) => s.stage));
+    for (const required of REQUIRED_STAGES) {
+        if (!presentStages.has(required)) {
+            allIssues.push({
+                code: "MISSING_STAGE",
+                stage: required,
+                detail: `Required stage "${required}" is missing from the RPP record.`,
+            });
+        }
+    }
+    // For checks 2–7, iterate over present steps only
+    for (const step of record.steps) {
+        const stage = step.stage;
+        // --- Check 2: EMPTY_CONTENT ---
+        if (!step.content || step.content.length < 1) {
+            allIssues.push({
+                code: "EMPTY_CONTENT",
+                stage,
+                detail: `Stage "${stage}" has empty content array.`,
+            });
+        }
+        // --- Check 3: NO_REFERENCES ---
+        if (!step.references || step.references.length < 1) {
+            allIssues.push({
+                code: "NO_REFERENCES",
+                stage,
+                detail: `Stage "${stage}" has no references.`,
+            });
+        }
+        // --- Check 4: SUPPORTS_TOO_VAGUE (warning) ---
+        for (const ref of step.references ?? []) {
+            if (ref.supports.length < 10) {
+                allIssues.push({
+                    code: "SUPPORTS_TOO_VAGUE",
+                    stage,
+                    detail: `Reference in stage "${stage}" has a 'supports' field that is too vague: "${ref.supports}".`,
+                });
+            }
+        }
+        // --- Check 5: INVALID_REFERENCE ---
+        for (const ref of step.references ?? []) {
+            const failure = validateReference(ref, stage);
+            if (failure) {
+                allIssues.push(failure);
+            }
+        }
+    }
+    // --- Check 6: UNJUSTIFIED_DECISION ---
+    const decisionStep = record.steps.find((s) => s.stage === "decision");
+    if (decisionStep) {
+        const hasRuleOrMethod = decisionStep.references.some((ref) => ref.type === "rule" || ref.type === "method");
+        if (!hasRuleOrMethod) {
+            allIssues.push({
+                code: "UNJUSTIFIED_DECISION",
+                stage: "decision",
+                detail: `Decision stage has no rule or method reference to justify the decision.`,
+            });
+        }
+    }
+    // --- Check 7: INFERENCE_AS_FACT (warning) ---
+    const reasoningStep = record.steps.find((s) => s.stage === "reasoning");
+    if (reasoningStep) {
+        const hasEvidenceRef = reasoningStep.references.some((ref) => ref.type === "evidence");
+        if (!hasEvidenceRef) {
+            for (const contentItem of reasoningStep.content ?? []) {
+                const lower = contentItem.toLowerCase();
+                const hasCertaintyWord = CERTAINTY_WORDS.some((word) => lower.includes(word));
+                if (hasCertaintyWord) {
+                    allIssues.push({
+                        code: "INFERENCE_AS_FACT",
+                        stage: "reasoning",
+                        detail: `Reasoning stage content uses certainty language ("${CERTAINTY_WORDS.find((w) => lower.includes(w))}") without any evidence reference: "${contentItem.slice(0, 80)}${contentItem.length > 80 ? "..." : ""}"`,
+                    });
+                }
+            }
+        }
+    }
+    // --- Check 8: UNTRACEABLE_RESPONSE ---
+    // Gather all prior step content strings
+    const allPriorContent = record.steps.flatMap((s) => s.content ?? []).map((c) => c.toLowerCase());
+    if (record.response.content.length > 0) {
+        let anyTraced = false;
+        for (const responseItem of record.response.content) {
+            const keyPhrase = extractFirstKeyPhrase(responseItem);
+            if (keyPhrase !== null) {
+                const traced = allPriorContent.some((priorContent) => priorContent.includes(keyPhrase));
+                if (traced) {
+                    anyTraced = true;
+                    break;
+                }
+            }
+        }
+        if (!anyTraced) {
+            allIssues.push({
+                code: "UNTRACEABLE_RESPONSE",
+                stage: "response",
+                detail: `None of the response content items could be traced back to any prior step's content.`,
+            });
+        }
+    }
+    // --- Compute overall_status ---
+    const failures = allIssues.filter((issue) => isHardFailure(issue.code));
+    const warnings = allIssues.filter((issue) => !isHardFailure(issue.code));
+    let overall_status;
+    if (failures.length > 0) {
+        overall_status = "invalid";
+    }
+    else if (warnings.length > 0) {
+        overall_status = "weakly_supported";
+    }
+    else {
+        overall_status = "valid";
+    }
+    return { overall_status, failures, warnings };
+}
+//# sourceMappingURL=rpp.validate.js.map

package/dist/src/rpp/rpp.validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpp.validate.js","sourceRoot":"","sources":["../../../src/rpp/rpp.validate.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAG1B,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAEjD,MAAM,eAAe,GAAkC;IACrD,gBAAgB;IAChB,WAAW;IACX,UAAU;IACV,QAAQ;CACT,CAAA;AAED,MAAM,sBAAsB,GAAG,cAAc,CAAA;AAE7C,MAAM,eAAe,GAAG;IACtB,eAAe;IACf,QAAQ;IACR,OAAO;IACP,SAAS;IACT,WAAW;CACZ,CAAA;AAED,SAAS,iBAAiB,CAAC,GAAc,EAAE,KAA0C;IACnF,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACxB,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9C,OAAO;gBACL,IAAI,EAAE,mBAAmB;gBACzB,KAAK;gBACL,MAAM,EAAE,iCAAiC,GAAG,CAAC,OAAO,gCAAgC;aACrF,CAAA;QACH,CAAC;IACH,CAAC;SAAM,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACjC,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAChD,OAAO;gBACL,IAAI,EAAE,mBAAmB;gBACzB,KAAK;gBACL,MAAM,EAAE,qCAAqC,GAAG,CAAC,SAAS,gCAAgC;aAC3F,CAAA;QACH,CAAC;IACH,CAAC;SAAM,IAAI,GAAG,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QACnC,IAAI,CAAC,GAAG,CAAC,MAAM,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YAC9E,OAAO;gBACL,IAAI,EAAE,mBAAmB;gBACzB,KAAK;gBACL,MAAM,EAAE,kDAAkD;aAC3D,CAAA;QACH,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,OAAO,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACjF,OAAO;gBACL,IAAI,EAAE,mBAAmB;gBACzB,KAAK;gBACL,MAAM,EAAE,mDAAmD;aAC5D,CAAA;QACH,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;GAGG;AACH,SAAS,qBAAqB,CAAC,IAAY;IACzC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC,CAAA;QACjD,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YACxB,OAAO,OAAO,CAAC,WAAW,EAAE,CAAA;QAC9B,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,MAAiB;IAC3C,MAAM,SAAS,GAAiB,EAAE,CAAA;IAElC,iCAAiC;IACjC,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;IAC/D,KAAK,MAAM,QAAQ,IAAI,eAAe,EAAE,CAAC;QACvC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YACjC,SAAS,CAAC,IAAI,CAAC;gBACb,IAAI,EAAE,eAAe;gBACrB,KAAK,EAAE,QAAQ;gBACf,MAAM,EAAE,mBAAmB,QAAQ,mCAAmC;aACvE,CAAC,CAAA;QACJ,CAAC;IACH,CAAC;IAED,kDAAkD;IAClD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;QAExB,iCAAiC;QACjC,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7C,SAAS,CAAC,IAAI,CAAC;gBACb,IAAI,EAAE,eAAe;gBACrB,KAAK;gBACL,MAAM,EAAE,UAAU,KAAK,4BAA4B;aACpD,CAAC,CAAA;QACJ,CAAC;QAED,iCAAiC;QACjC,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACnD,SAAS,CAAC,IAAI,CAAC;gBACb,IAAI,EAAE,eAAe;gBACrB,KAAK;gBACL,MAAM,EAAE,UAAU,KAAK,sBAAsB;aAC9C,CAAC,CAAA;QACJ,CAAC;QAED,gDAAgD;QAChD,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC;YACxC,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;gBAC7B,SAAS,CAAC,IAAI,CAAC;oBACb,IAAI,EAAE,oBAAoB;oBAC1B,KAAK;oBACL,MAAM,EAAE,uBAAuB,KAAK,gDAAgD,GAAG,CAAC,QAAQ,IAAI;iBACrG,CAAC,CAAA;YACJ,CAAC;QACH,CAAC;QAED,qCAAqC;QACrC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC;YACxC,MAAM,OAAO,GAAG,iBAAiB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;YAC7C,IAAI,OAAO,EAAE,CAAC;gBACZ,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IAED,wCAAwC;IACxC,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,UAAU,CAAC,CAAA;IACrE,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,eAAe,GAAG,YAAY,CAAC,UAAU,CAAC,IAAI,CAClD,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,CACtD,CAAA;QACD,IAAI,CAAC,eAAe,EAAE,CAAC;YACrB,SAAS,CAAC,IAAI,CAAC;gBACb,IAAI,EAAE,sBAAsB;gBAC5B,KAAK,EAAE,UAAU;gBACjB,MAAM,EAAE,yEAAyE;aAClF,CAAC,CAAA;QACJ,CAAC;IACH,CAAC;IAED,+CAA+C;IAC/C,MAAM,aAAa,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,WAAW,CAAC,CAAA;IACvE,IAAI,aAAa,EAAE,CAAC;QAClB,MAAM,cAAc,GAAG,aAAa,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,UAAU,CAAC,CAAA;QACtF,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,KAAK,MAAM,WAAW,IAAI,aAAa,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;gBACtD,MAAM,KAAK,GAAG,WAAW,CAAC,WAAW,EAAE,CAAA;gBACvC,MAAM,gBAAgB,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAA;gBAC7E,IAAI,gBAAgB,EAAE,CAAC;oBACrB,SAAS,CAAC,IAAI,CAAC;wBACb,IAAI,EAAE,mBAAmB;wBACzB,KAAK,EAAE,WAAW;wBAClB,MAAM,EAAE,qDAAqD,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,uCAAuC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,WAAW,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG;qBACrN,CAAC,CAAA;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,wCAAwC;IACxC,wCAAwC;IACxC,MAAM,eAAe,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAA;IAEhG,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvC,IAAI,SAAS,GAAG,KAAK,CAAA;QACrB,KAAK,MAAM,YAAY,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;YACnD,MAAM,SAAS,GAAG,qBAAqB,CAAC,YAAY,CAAC,CAAA;YACrD,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;gBACvB,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAA;gBACvF,IAAI,MAAM,EAAE,CAAC;oBACX,SAAS,GAAG,IAAI,CAAA;oBAChB,MAAK;gBACP,CAAC;YACH,CAAC;QACH,CAAC;QACD,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,SAAS,CAAC,IAAI,CAAC;gBACb,IAAI,EAAE,sBAAsB;gBAC5B,KAAK,EAAE,UAAU;gBACjB,MAAM,EAAE,sFAAsF;aAC/F,CAAC,CAAA;QACJ,CAAC;IACH,CAAC;IAED,iCAAiC;IACjC,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;IACvE,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;IAExE,IAAI,cAAqD,CAAA;IACzD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,cAAc,GAAG,SAAS,CAAA;IAC5B,CAAC;SAAM,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,cAAc,GAAG,kBAAkB,CAAA;IACrC,CAAC;SAAM,CAAC;QACN,cAAc,GAAG,OAAO,CAAA;IAC1B,CAAC;IAED,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAA;AAC/C,CAAC"}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "jingu-protocol",
+  "version": "0.1.0",
+  "description": "Shared protocol types for the Jingu system — RPP (Reasoning Provenance Protocol) and related definitions",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/src/index.js",
+      "import": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test dist/src/**/*.test.js"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  }
+}