@agenticprimitives/provenance 0.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentic Trust Labs
+
+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/README.md

@@ -0,0 +1,28 @@
+# @agenticprimitives/provenance
+
+The Ring-0 **provenance projector** (spec 316 §6). It maps fabric exchanges + orchestration runs into a
+**private PROV-O / P-Plan A-box**, and enforces the ADR-0040 **public-projection firewall (S1)** on any
+candidate world-readable row.
+
+## What it owns
+- **PROV-O A-box types** — `ProvActivity` (`CommunicationDelivery`/`IntentInvocation`/`OrchestratedTask` ⊑
+  `prov:Activity`), `ProvEntity`, `ProvAgentRef` (classified per ADR-0046), and **P-Plan** (`PPlanPlan`/
+  `PPlanStep`) grounding orchestration plans.
+- **`projectExchangeProvenance`** / **`projectRunProvenance`** — the projectors (one trace: intent → plan →
+  executed activities → outcome, §15).
+- **`isPublicProjectionSafe` / `assertPublicProjectionSafe`** — the S1 firewall.
+
+## Hard rules
+- **Sole writer of the PRIVATE vault A-box; it NEVER writes the public discovery KB.** The public KB has one
+  writer — the indexer — projecting on-chain facts (§6 / B1). There is no `fabric → public-KB` path.
+- **S1 firewall (ADR-0040), fail-closed.** A public row is admissible ONLY if it carries a resolvable on-chain
+  anchor (`0x`+64 hex) + `OnchainConfirmed` assurance, AND has ZERO `actedOnBehalfOf` edges, ZERO person
+  attribution, ZERO inline plaintext, ZERO off-chain (`hmac-sha256:`) commitment fields.
+- **Leaf, zero deps.** It takes STRUCTURAL input (plain fields) — never fabric's `ExchangeRecordV1` (which
+  would cycle: `fabric → provenance`). fabric adapts its record to these shapes.
+
+## Validate
+```bash
+pnpm --filter @agenticprimitives/provenance typecheck
+pnpm --filter @agenticprimitives/provenance test
+```

package/dist/firewall.d.ts

@@ -0,0 +1,27 @@
+import type { AgentClass } from './types.js';
+/** A candidate world-readable KB row derived from a privileged outcome. */
+export interface PublicProvenanceRow {
+    /** Outcome class (e.g. `DecisionArtifact` / `Artifact` / `PaymentReceipt`). */
+    type: string;
+    /** REQUIRED: the on-chain attestation UID anchoring this row (`apvr:anchoredBy`) — `0x` + 64 lowercase hex. */
+    anchoredBy?: string;
+    /** REQUIRED: the assurance floor — must be `OnchainConfirmed`. */
+    assurance?: string;
+    /** `prov:actedOnBehalfOf` / `apfab:onBehalfOf` edges — MUST be empty for a public row. */
+    actedOnBehalfOf?: string[];
+    /** `prov:wasAttributedTo` agent classes — MUST NOT include `person`. */
+    attributedToClasses?: AgentClass[];
+    /** Arbitrary row properties — scanned for forbidden private/off-chain content. */
+    properties?: Record<string, unknown>;
+}
+export type FirewallResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** S1 firewall — is this row safe to project into the public discovery KB? Fail-closed. */
+export declare function isPublicProjectionSafe(row: PublicProvenanceRow): FirewallResult;
+/** S1 firewall (throwing variant) — use at the boundary where a row would be handed to the public projector. */
+export declare function assertPublicProjectionSafe(row: PublicProvenanceRow): void;
+//# sourceMappingURL=firewall.d.ts.map

package/dist/firewall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"firewall.d.ts","sourceRoot":"","sources":["../src/firewall.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,+GAA+G;IAC/G,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,wEAAwE;IACxE,mBAAmB,CAAC,EAAE,UAAU,EAAE,CAAC;IACnC,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAgC1E,2FAA2F;AAC3F,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,mBAAmB,GAAG,cAAc,CAY/E;AAED,gHAAgH;AAChH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,mBAAmB,GAAG,IAAI,CAGzE"}

package/dist/firewall.js

@@ -0,0 +1,60 @@
+const ANCHOR = /^0x[0-9a-f]{64}$/;
+const OFFCHAIN_HMAC = /^hmac-sha256:/;
+const FORBIDDEN_PLAINTEXT_KEYS = new Set(['body', 'args', 'plaintext']);
+const FORBIDDEN_OFFCHAIN_KEYS = new Set(['principalCommitment']);
+// A forbidden key at ANY nesting depth is a leak (FAB-2: the shallow top-level scan let
+// `properties:{meta:{body:…}}` through). The scan recurses into nested objects/arrays.
+const MAX_SCAN_DEPTH = 8;
+/** Recursively reject any forbidden key or off-chain-HMAC string value at any depth. */
+function scanForbidden(value, keyPath, depth) {
+    if (depth > MAX_SCAN_DEPTH)
+        return `scan_depth_exceeded:${keyPath}`; // fail-closed on pathological nesting
+    if (typeof value === 'string')
+        return OFFCHAIN_HMAC.test(value) ? `offchain_hmac_field:${keyPath}` : null;
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            const r = scanForbidden(value[i], `${keyPath}[${i}]`, depth + 1);
+            if (r)
+                return r;
+        }
+        return null;
+    }
+    if (value && typeof value === 'object') {
+        for (const [k, v] of Object.entries(value)) {
+            if (FORBIDDEN_OFFCHAIN_KEYS.has(k))
+                return `offchain_commitment_field:${keyPath}${k}`;
+            if (FORBIDDEN_PLAINTEXT_KEYS.has(k) && v != null)
+                return `inline_plaintext:${keyPath}${k}`;
+            const r = scanForbidden(v, `${keyPath}${k}.`, depth + 1);
+            if (r)
+                return r;
+        }
+    }
+    return null;
+}
+/** S1 firewall — is this row safe to project into the public discovery KB? Fail-closed. */
+export function isPublicProjectionSafe(row) {
+    // (necessary) — no private / off-chain content
+    if ((row.actedOnBehalfOf ?? []).length > 0)
+        return { ok: false, reason: 'actedOnBehalfOf_edge_present' };
+    if ((row.attributedToClasses ?? []).includes('person'))
+        return { ok: false, reason: 'person_attribution' };
+    // Recursive denylist scan — nested `body`/`args`/`plaintext`/`principalCommitment` keys or `hmac-sha256:`
+    // string values at ANY depth are rejected, not just top-level (FAB-2).
+    const forbidden = scanForbidden(row.properties ?? {}, '', 0);
+    if (forbidden)
+        return { ok: false, reason: forbidden };
+    // (sufficient) — on-chain anchor + assurance floor
+    if (!row.anchoredBy || !ANCHOR.test(row.anchoredBy))
+        return { ok: false, reason: 'missing_or_malformed_anchor' };
+    if (row.assurance !== 'OnchainConfirmed')
+        return { ok: false, reason: 'assurance_below_floor' };
+    return { ok: true };
+}
+/** S1 firewall (throwing variant) — use at the boundary where a row would be handed to the public projector. */
+export function assertPublicProjectionSafe(row) {
+    const r = isPublicProjectionSafe(row);
+    if (!r.ok)
+        throw new Error(`S1 firewall: public provenance row rejected (${r.reason})`);
+}
+//# sourceMappingURL=firewall.js.map

package/dist/firewall.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export declare const PACKAGE_NAME = "@agenticprimitives/provenance";
+export declare const PACKAGE_STATUS: "w5-projector";
+export declare const SPEC_REF = "specs/316-agentic-interaction-fabric.md";
+export type { Tier, AgentClass, ProvAgentRef, ProvActivityType, ProvActivity, ProvEntityType, ProvEntity, PPlanStep, PPlanPlan, ProvenanceRecordV1, } from './types.js';
+export { projectExchangeProvenance, projectRunProvenance, type ProvenanceExchangeInput, type ProvenanceRunInput, } from './project.js';
+export { isPublicProjectionSafe, assertPublicProjectionSafe, type PublicProvenanceRow, type FirewallResult, } from './firewall.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,YAAY,kCAAkC,CAAC;AAC5D,eAAO,MAAM,cAAc,EAAG,cAAuB,CAAC;AACtD,eAAO,MAAM,QAAQ,4CAA4C,CAAC;AAElE,YAAY,EACV,IAAI,EACJ,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,UAAU,EACV,SAAS,EACT,SAAS,EACT,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,yBAAyB,EACzB,oBAAoB,EACpB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,sBAAsB,EACtB,0BAA0B,EAC1B,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+// @agenticprimitives/provenance — the Ring-0 provenance projector (spec 316 §6). Sole writer of the PRIVATE
+// PROV-O / P-Plan A-box; NEVER writes the public discovery KB (the indexer does, from on-chain facts). The S1
+// firewall enforces the ADR-0040 rule on any candidate public row.
+export const PACKAGE_NAME = '@agenticprimitives/provenance';
+export const PACKAGE_STATUS = 'w5-projector';
+export const SPEC_REF = 'specs/316-agentic-interaction-fabric.md';
+export { projectExchangeProvenance, projectRunProvenance, } from './project.js';
+export { isPublicProjectionSafe, assertPublicProjectionSafe, } from './firewall.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4GAA4G;AAC5G,8GAA8G;AAC9G,mEAAmE;AACnE,MAAM,CAAC,MAAM,YAAY,GAAG,+BAA+B,CAAC;AAC5D,MAAM,CAAC,MAAM,cAAc,GAAG,cAAuB,CAAC;AACtD,MAAM,CAAC,MAAM,QAAQ,GAAG,yCAAyC,CAAC;AAelE,OAAO,EACL,yBAAyB,EACzB,oBAAoB,GAGrB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,sBAAsB,EACtB,0BAA0B,GAG3B,MAAM,eAAe,CAAC"}

package/dist/project.d.ts

@@ -0,0 +1,40 @@
+import type { ProvenanceRecordV1, PPlanPlan, Tier, AgentClass } from './types.js';
+/** Structural projection of a fabric exchange (never the fabric type — leaf boundary). */
+export interface ProvenanceExchangeInput {
+    exchangeId: string;
+    tier: Tier;
+    /** The acting agent (gateway owner / responder). */
+    principal: string;
+    principalClass?: AgentClass;
+    from: string;
+    fromClass?: AgentClass;
+    at: string;
+    endedAt?: string;
+    /** BY-HASH delegation / entitlement / status-evidence refs (`prov:used`) — never inline authority. */
+    authorityRefs?: string[];
+    /** PRIVATE — the ultimate principal the actor acts for (`prov:actedOnBehalfOf`). Detail-tier only. */
+    onBehalfOf?: string;
+    /** The message / artifact produced, as a vault ref or hash (never inline plaintext). */
+    outputRef?: string;
+}
+/**
+ * Project one exchange into the private A-box: one activity (`CommunicationDelivery`/`IntentInvocation`/
+ * `OrchestratedTask`), the message/artifact entity it generated (if any, by-ref), and the acting + sender
+ * agents. `onBehalfOf` and `used` carry the private authority detail; a public row is derived SEPARATELY and
+ * must pass the S1 firewall (`./firewall`).
+ */
+export declare function projectExchangeProvenance(input: ProvenanceExchangeInput): ProvenanceRecordV1;
+/** Structural projection of an orchestration run (never the orchestration `RunResult` type — leaf boundary). */
+export interface ProvenanceRunInput {
+    exchangeId: string;
+    goal: string;
+    steps: Array<{
+        toolId: string;
+    }>;
+}
+/** Project an orchestration run into a P-Plan (the `Plan` + its `Step`s), bridged to the exchange's
+ *  `OrchestratedTask` activity by convention (`plan:<exchangeId>` ↔ `act:<exchangeId>`; §6/§15 — one trace). */
+export declare function projectRunProvenance(input: ProvenanceRunInput): {
+    plan: PPlanPlan;
+};
+//# sourceMappingURL=project.d.ts.map

package/dist/project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,kBAAkB,EAKlB,SAAS,EACT,IAAI,EACJ,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB,0FAA0F;AAC1F,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,IAAI,CAAC;IACX,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,UAAU,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,UAAU,CAAC;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sGAAsG;IACtG,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,sGAAsG;IACtG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAKD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,uBAAuB,GAAG,kBAAkB,CA2B5F;AAED,gHAAgH;AAChH,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClC;AAED;gHACgH;AAChH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,kBAAkB,GAAG;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAQnF"}

package/dist/project.js

@@ -0,0 +1,43 @@
+const activityType = (tier) => tier === 'communication' ? 'CommunicationDelivery' : tier === 'execution-orchestrated' ? 'OrchestratedTask' : 'IntentInvocation';
+/**
+ * Project one exchange into the private A-box: one activity (`CommunicationDelivery`/`IntentInvocation`/
+ * `OrchestratedTask`), the message/artifact entity it generated (if any, by-ref), and the acting + sender
+ * agents. `onBehalfOf` and `used` carry the private authority detail; a public row is derived SEPARATELY and
+ * must pass the S1 firewall (`./firewall`).
+ */
+export function projectExchangeProvenance(input) {
+    const activityId = `act:${input.exchangeId}`;
+    const entityId = `ent:${input.exchangeId}`;
+    const type = activityType(input.tier);
+    const activity = {
+        id: activityId,
+        type,
+        tier: input.tier,
+        startedAt: input.at,
+        endedAt: input.endedAt,
+        wasAssociatedWith: input.principal,
+        used: input.authorityRefs ?? [],
+        onBehalfOf: input.onBehalfOf,
+        generated: input.outputRef ? [entityId] : [],
+    };
+    const entities = input.outputRef
+        ? [{ id: entityId, type: type === 'OrchestratedTask' ? 'Artifact' : 'Message', wasGeneratedBy: activityId, ref: input.outputRef }]
+        : [];
+    const agents = [{ id: input.principal, agentClass: input.principalClass ?? 'service' }];
+    if (input.from.toLowerCase() !== input.principal.toLowerCase()) {
+        agents.push({ id: input.from, agentClass: input.fromClass ?? 'service' });
+    }
+    return { version: 'ap.provenance.v1', agents, activities: [activity], entities, plans: [] };
+}
+/** Project an orchestration run into a P-Plan (the `Plan` + its `Step`s), bridged to the exchange's
+ *  `OrchestratedTask` activity by convention (`plan:<exchangeId>` ↔ `act:<exchangeId>`; §6/§15 — one trace). */
+export function projectRunProvenance(input) {
+    const planId = `plan:${input.exchangeId}`;
+    return {
+        plan: {
+            id: planId,
+            steps: input.steps.map((s, i) => ({ id: `${planId}:step:${i}`, toolId: s.toolId, isStepOfPlan: planId })),
+        },
+    };
+}
+//# sourceMappingURL=project.js.map

package/dist/project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAgCA,MAAM,YAAY,GAAG,CAAC,IAAU,EAAoB,EAAE,CACpD,IAAI,KAAK,eAAe,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,IAAI,KAAK,wBAAwB,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,kBAAkB,CAAC;AAEnI;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAA8B;IACtE,MAAM,UAAU,GAAG,OAAO,KAAK,CAAC,UAAU,EAAE,CAAC;IAC7C,MAAM,QAAQ,GAAG,OAAO,KAAK,CAAC,UAAU,EAAE,CAAC;IAC3C,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAEtC,MAAM,QAAQ,GAAiB;QAC7B,EAAE,EAAE,UAAU;QACd,IAAI;QACJ,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,SAAS,EAAE,KAAK,CAAC,EAAE;QACnB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,iBAAiB,EAAE,KAAK,CAAC,SAAS;QAClC,IAAI,EAAE,KAAK,CAAC,aAAa,IAAI,EAAE;QAC/B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE;KAC7C,CAAC;IAEF,MAAM,QAAQ,GAAiB,KAAK,CAAC,SAAS;QAC5C,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,KAAK,kBAAkB,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,GAAG,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;QAClI,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,MAAM,GAAmB,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,SAAS,EAAE,UAAU,EAAE,KAAK,CAAC,cAAc,IAAI,SAAS,EAAE,CAAC,CAAC;IACxG,IAAI,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC,SAAS,CAAC,WAAW,EAAE,EAAE,CAAC;QAC/D,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,CAAC,SAAS,IAAI,SAAS,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;AAC9F,CAAC;AASD;gHACgH;AAChH,MAAM,UAAU,oBAAoB,CAAC,KAAyB;IAC5D,MAAM,MAAM,GAAG,QAAQ,KAAK,CAAC,UAAU,EAAE,CAAC;IAC1C,OAAO;QACL,IAAI,EAAE;YACJ,EAAE,EAAE,MAAM;YACV,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,GAAG,MAAM,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,CAAC;SAC1G;KACF,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,56 @@
+export type Tier = 'communication' | 'execution-fast' | 'execution-orchestrated';
+export type AgentClass = 'person' | 'org' | 'service';
+/** PROV-O agent (`prov:Agent`), classified per ADR-0046. */
+export interface ProvAgentRef {
+    id: string;
+    agentClass: AgentClass;
+}
+/** `apfab:CommunicationDelivery` (T0) / `apfab:IntentInvocation` (T1) / `apfab:OrchestratedTask ≡ apful:Task`
+ *  (T2) — all `⊑ prov:Activity` (§6). */
+export type ProvActivityType = 'CommunicationDelivery' | 'IntentInvocation' | 'OrchestratedTask';
+export interface ProvActivity {
+    id: string;
+    type: ProvActivityType;
+    tier: Tier;
+    startedAt: string;
+    endedAt?: string;
+    /** `prov:wasAssociatedWith` — the acting agent id. */
+    wasAssociatedWith: string;
+    /** `apfab:usedDelegation`/`usedStatusEvidence ⊑ prov:used` — BY-HASH refs, never inline authority. */
+    used: string[];
+    /** `apfab:onBehalfOf ⊑ prov:actedOnBehalfOf` — **PRIVATE DETAIL ONLY** (the S1 firewall rejects it from any
+     *  public row). */
+    onBehalfOf?: string;
+    /** `prov:generated` — entity ids this activity produced. */
+    generated: string[];
+}
+export type ProvEntityType = 'Message' | 'Artifact' | 'DecisionArtifact';
+export interface ProvEntity {
+    id: string;
+    type: ProvEntityType;
+    /** `prov:wasGeneratedBy` — the activity id. */
+    wasGeneratedBy?: string;
+    /** Vault-resident ref (hash / VaultRef) — NEVER inline plaintext. */
+    ref?: string;
+}
+/** P-Plan (`tbox/plan.ttl`) — grounds an orchestration `Plan` (and a service-agent `PrimitivePlan`) as
+ *  `p-plan:Plan`; steps are `p-plan:Step` via `isStepOfPlan` (§6). */
+export interface PPlanStep {
+    id: string;
+    toolId: string;
+    isStepOfPlan: string;
+}
+export interface PPlanPlan {
+    id: string;
+    steps: PPlanStep[];
+}
+/** The PRIVATE vault A-box the projector writes — the ONLY surface this package emits. It NEVER writes the
+ *  public discovery KB (that has exactly one writer, the indexer, projecting on-chain facts; §6 / B1). */
+export interface ProvenanceRecordV1 {
+    version: 'ap.provenance.v1';
+    agents: ProvAgentRef[];
+    activities: ProvActivity[];
+    entities: ProvEntity[];
+    plans: PPlanPlan[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,IAAI,GAAG,eAAe,GAAG,gBAAgB,GAAG,wBAAwB,CAAC;AACjF,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;AAEtD,4DAA4D;AAC5D,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,UAAU,CAAC;CACxB;AAED;yCACyC;AACzC,MAAM,MAAM,gBAAgB,GAAG,uBAAuB,GAAG,kBAAkB,GAAG,kBAAkB,CAAC;AAEjG,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,IAAI,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,sGAAsG;IACtG,IAAI,EAAE,MAAM,EAAE,CAAC;IACf;uBACmB;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,GAAG,kBAAkB,CAAC;AAEzE,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,cAAc,CAAC;IACrB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;sEACsE;AACtE,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB;AACD,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED;0GAC0G;AAC1G,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB"}

package/dist/types.js

@@ -0,0 +1,4 @@
+// PROV-O + P-Plan A-box types (spec 316 §6). This package is a LEAF (fabric → provenance, §8), so it takes
+// STRUCTURAL input (plain fields) — never fabric's `ExchangeRecordV1` (which would cycle) — and has zero deps.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,2GAA2G;AAC3G,+GAA+G"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@agenticprimitives/provenance",
+  "version": "0.0.0-alpha.0",
+  "description": "The Ring-0 provenance projector (spec 316 §6): maps fabric exchanges + orchestration runs to a PRIVATE PROV-O / P-Plan A-box, and enforces the ADR-0040 public-projection firewall (S1). Sole writer of the private vault A-box; NEVER writes the public KB.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentictrustlabs/agenticprimitives.git",
+    "directory": "packages/provenance"
+  },
+  "homepage": "https://github.com/agentictrustlabs/agenticprimitives/tree/master/packages/provenance",
+  "bugs": {
+    "url": "https://github.com/agentictrustlabs/agenticprimitives/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "LICENSE",
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.8",
+    "@types/node": "^22.7.0"
+  },
+  "keywords": [
+    "agentic",
+    "primitives",
+    "provenance",
+    "prov-o",
+    "p-plan",
+    "privacy"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:unit": "vitest run test/unit --passWithNoTests",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}