@agenticprimitives/ontology 1.0.0-alpha.22 → 1.0.0-alpha.24

package/cbox/run-provenance-shapes.shacl.ttl

@@ -0,0 +1,172 @@
+# C-box — SHACL shapes for a harness run's provenance record (spec 389 W2).
+#
+# WHAT THESE ARE AND ARE NOT. A run's vault record (`run.provenance:<runRef>`) is a PROV graph: one
+# ep-plan:ExecutionTraceBundle holding the run (apexec:ServiceExecution), its steps, what they used and
+# what they generated. These shapes say what makes such a graph VALID AS EVIDENCE — a step that ended
+# before it started, a completed capability step with no mandate behind it, a completed step with no
+# receipt, a reference to nothing, a member missing from the bundle, a literal that carries an address —
+# each is a record that reads fine today and cannot be trusted in a year.
+#
+# NEVER PERMISSION. Conformance does not mean the run was authorized, and a REFUSED step is fully
+# shape-valid (R3 targets only COMPLETED capability steps): refusing to record a refusal would delete the
+# evidence an audit most needs (ADR-0058's rule, unchanged). No verifier reads these shapes or the record
+# they validate (spec 354 §1 / ADR-0041). They run in CI over records the projector built, and over the
+# forged / truncated / leaking twins that must fail them.
+#
+# ENGINE NOTES. One sh:sparql per NodeShape (shacl-engine compiles them as one unit). sh:targetClass
+# relies on the rdfs:subClassOf* closure the house harness materializes. R5 and R6 are scoped to the
+# bundle's own members (`ep-plan:hasTraceElement`) so the T-box unioned into the data graph — whose
+# comments legitimately quote addresses — is never in scope.
+
+@prefix apexec:  <https://agenticprimitives.dev/ns/execution#> .
+@prefix apvr:    <https://agenticprimitives.dev/ns/verification-receipt#> .
+@prefix prov:    <http://www.w3.org/ns/prov#> .
+@prefix p-plan:  <http://purl.org/net/p-plan#> .
+@prefix ep-plan: <https://w3id.org/ep-plan#> .
+@prefix sh:      <http://www.w3.org/ns/shacl#> .
+@prefix rdfs:    <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd:     <http://www.w3.org/2001/XMLSchema#> .
+
+# ─── R1 · temporal order ─────────────────────────────────────────────────────
+
+apexec:ActivityTemporalOrderShape a sh:NodeShape ;
+  rdfs:label "R1a — an activity ends no earlier than it starts" ;
+  sh:targetClass prov:Activity ;
+  sh:sparql [
+    sh:message "R1: the activity ended before it started — a record with time running backwards is not evidence (spec 389 W2)." ;
+    sh:select """
+      SELECT $this ?started ?ended WHERE {
+        $this <http://www.w3.org/ns/prov#startedAtTime> ?started ;
+              <http://www.w3.org/ns/prov#endedAtTime> ?ended .
+        FILTER(STR(?ended) < STR(?started))
+      }
+    """ ;
+  ] .
+
+apexec:RunTemporalOrderShape a sh:NodeShape ;
+  rdfs:label "R1b — a step ends no later than its run" ;
+  sh:targetClass apexec:ServiceExecution ;
+  sh:sparql [
+    sh:message "R1: a step of this run ended after the run itself ended (spec 389 W2)." ;
+    sh:select """
+      SELECT $this ?step ?stepEnd ?runEnd WHERE {
+        $this <https://agenticprimitives.dev/ns/execution#hasStep> ?step ;
+              <http://www.w3.org/ns/prov#endedAtTime> ?runEnd .
+        ?step <http://www.w3.org/ns/prov#endedAtTime> ?stepEnd .
+        FILTER(STR(?stepEnd) > STR(?runEnd))
+      }
+    """ ;
+  ] .
+
+# ─── R2 · references resolve; generation is mutual ──────────────────────────
+
+apexec:StepUsageResolvableShape a sh:NodeShape ;
+  rdfs:label "R2 — what a step used is in the graph; what it generated points back" ;
+  sh:targetClass prov:Activity ;
+  sh:sparql [
+    sh:message "R2: the activity used or generated something the graph does not describe — a reference to nothing, or a generated entity that does not name this activity as its generator (spec 389 W2)." ;
+    sh:select """
+      SELECT $this ?ref WHERE {
+        {
+          { $this <http://www.w3.org/ns/prov#used> ?ref } UNION { $this <https://agenticprimitives.dev/ns/verification-receipt#usedDelegation> ?ref }
+          FILTER NOT EXISTS { ?ref a ?anyType }
+        }
+        UNION
+        {
+          $this <http://www.w3.org/ns/prov#generated> ?ref .
+          FILTER NOT EXISTS { ?ref <http://www.w3.org/ns/prov#wasGeneratedBy> $this }
+        }
+      }
+    """ ;
+  ] .
+
+# ─── R3 · a completed capability step ran under a mandate that allowed it ────
+
+apexec:CapabilityStepMandateShape a sh:NodeShape ;
+  rdfs:label "R3 — a completed capability step presented a mandate and the verdict was allow" ;
+  sh:target [
+    sh:select """
+      SELECT ?this WHERE {
+        ?this <https://agenticprimitives.dev/ns/execution#realizesCapability> ?cap ;
+              <https://agenticprimitives.dev/ns/execution#completionState> <https://agenticprimitives.dev/ns/execution#Completed> .
+      }
+    """ ;
+  ] ;
+  sh:property [
+    sh:path apvr:usedDelegation ;
+    sh:minCount 1 ; sh:nodeKind sh:IRI ;
+    sh:message "R3: a COMPLETED capability step names no mandate (apvr:usedDelegation) — a consequential act with nothing behind it is a forged record, not a run (spec 389 W2; spec 350: every consequential step presents a mandate)." ;
+  ] ;
+  sh:property [
+    sh:path apexec:authorityDecision ;
+    sh:minCount 1 ; sh:in ( "allow" ) ;
+    sh:message "R3: a COMPLETED capability step records a verdict other than allow — a step that completed under a deny is a record that contradicts itself (spec 389 W2)." ;
+  ] .
+
+# ─── R4 · a completed step left its receipt ──────────────────────────────────
+
+apexec:CompletedStepReceiptShape a sh:NodeShape ;
+  rdfs:label "R4 — a completed step carries its receipt digest and generated its receipt" ;
+  sh:target [
+    sh:select """
+      SELECT ?this WHERE {
+        ?this <http://purl.org/net/p-plan#correspondsToStep> ?planStep ;
+              <https://agenticprimitives.dev/ns/execution#completionState> <https://agenticprimitives.dev/ns/execution#Completed> .
+      }
+    """ ;
+  ] ;
+  sh:property [
+    sh:path apexec:receiptDigest ;
+    sh:minCount 1 ; sh:maxCount 1 ; sh:datatype xsd:string ; sh:pattern "^0x[0-9a-f]{64}$" ;
+    sh:message "R4: a COMPLETED step carries no receipt digest (or not a sha256) — the receipt is the commitment to what was done; without it the step is a claim (spec 389 W2; spec 381)." ;
+  ] ;
+  sh:sparql [
+    sh:message "R4: a COMPLETED step generated no apexec:StepReceipt entity — the digest on the activity and the receipt in the graph must both be there (spec 389 W2)." ;
+    sh:select """
+      SELECT $this WHERE {
+        FILTER NOT EXISTS {
+          $this <http://www.w3.org/ns/prov#generated> ?r .
+          ?r a <https://agenticprimitives.dev/ns/execution#StepReceipt> .
+        }
+      }
+    """ ;
+  ] .
+
+# ─── R5 · every node of the run is a member of its bundle ────────────────────
+
+apexec:ExecutionTraceBundleMembershipShape a sh:NodeShape ;
+  rdfs:label "R5 — every activity, agent and entity of the run is a hasTraceElement of the bundle" ;
+  sh:targetClass ep-plan:ExecutionTraceBundle ;
+  sh:property [
+    sh:path prov:wasAttributedTo ;
+    sh:minCount 1 ; sh:nodeKind sh:IRI ;
+    sh:message "R5: the bundle is attributed to no agent — whose record is this? (spec 389 W2; the vault it lives in is the acting agent's)." ;
+  ] ;
+  sh:sparql [
+    sh:message "R5: a node of the run is not a member of its bundle (ep-plan:hasTraceElement) — a graph whose members are not listed cannot be checked for what it omits (spec 389 W2)." ;
+    sh:select """
+      SELECT $this ?node WHERE {
+        { ?node a <http://www.w3.org/ns/prov#Activity> } UNION { ?node a <http://www.w3.org/ns/prov#Entity> } UNION { ?node a <http://www.w3.org/ns/prov#Agent> }
+        FILTER(?node != $this)
+        FILTER NOT EXISTS { $this <https://w3id.org/ep-plan#hasTraceElement> ?node }
+        FILTER NOT EXISTS { ?node a <http://www.w3.org/2002/07/owl#Class> }
+      }
+    """ ;
+  ] .
+
+# ─── R6 · no plaintext: no address, no long literal, among the bundle's members ─
+
+apexec:NoPlaintextInRunProvenanceShape a sh:NodeShape ;
+  rdfs:label "R6 — no literal of the run carries an address or a body" ;
+  sh:targetClass ep-plan:ExecutionTraceBundle ;
+  sh:sparql [
+    sh:message "R6: a literal in the run's provenance carries a Smart Agent address or is long enough to be a body — the record says what was done, never what it was about; a payee is a digest away from a receipt (spec 381 §1 / spec 389 W2)." ;
+    sh:select """
+      SELECT $this ?node ?p ?v WHERE {
+        { $this <https://w3id.org/ep-plan#hasTraceElement> ?node } UNION { BIND($this AS ?node) }
+        ?node ?p ?v .
+        FILTER(isLiteral(?v))
+        FILTER(REGEX(STR(?v), "(^|[^0-9a-fA-Fx])0x[0-9a-fA-F]{40}([^0-9a-fA-F]|$)") || STRLEN(STR(?v)) > 256)
+      }
+    """ ;
+  ] .

package/context.jsonld

@@ -33,7 +33,11 @@
     "apsit": "https://agenticprimitives.dev/ns/situation#",
     "apfo": "https://agenticprimitives.dev/ns/familyoffice#",
     "apent": "https://agenticprimitives.dev/ns/entitlement#",
-    "apfab": "https://agenticprimitives.dev/ns/fabric#",
+    "apix": "https://agenticprimitives.dev/ns/interaction#",
+    "apexec": "https://agenticprimitives.dev/ns/execution#",
+    "apactor": "https://agenticprimitives.dev/ns/actor#",
+    "apguide": "https://agenticprimitives.dev/ns/guidance#",
+    "apcoord": "https://agenticprimitives.dev/ns/coordination#",
 
     "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
     "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
@@ -42,6 +46,8 @@
     "sh": "http://www.w3.org/ns/shacl#",
     "skos": "http://www.w3.org/2004/02/skos/core#",
     "prov": "http://www.w3.org/ns/prov#",
+    "p-plan": "http://purl.org/net/p-plan#",
+    "ep-plan": "https://w3id.org/ep-plan#",
     "dul": "http://www.ontologydesignpatterns.org/ont/dul/DUL.owl#",
     "vf": "https://w3id.org/valueflows#",
     "ufo-c": "http://purl.org/nemo/ufo-c#",

package/dist/arg-types.d.ts

@@ -0,0 +1,60 @@
+import { type ClassIri } from './party-roles.js';
+export type ValueTypeName = 'Amount' | 'Asset' | 'EmailAddress' | 'DisplayLabel' | 'Flag' | 'AgentKind';
+/** The T-box term each type names. Checked by `check:ontology-bindings` like every other binding. */
+export declare const VALUE_TYPE_TERM: Readonly<Record<ValueTypeName, ClassIri>>;
+export interface ArgTypeBindingV1 {
+    /** The capability whose argument this is (ADR-0051 id). */
+    capability: string;
+    /** The argument name, as the tool declares it. */
+    arg: string;
+    type: ValueTypeName;
+    /** What to call it when asking a person for it. */
+    word: string;
+    /** A hint that says how to answer, in the person's terms. */
+    hint?: string;
+}
+/**
+ * Every non-party argument, and what it is.
+ *
+ * PARTY ARGUMENTS ARE NOT HERE — they are in `PARTY_ROLES`, which answers a different question (which
+ * CLASS of agent may fill it, and which relation to follow to get there). One argument, one table.
+ */
+export declare const ARG_TYPES: readonly ArgTypeBindingV1[];
+/** The type bound to one capability's argument, or undefined — undefined means "not a value we read", and
+ *  the argument passes through untouched, which is how every unbound argument behaved before this existed. */
+export declare function argType(capability: string, arg: string): ArgTypeBindingV1 | undefined;
+/** The value bindings of one capability — what a normaliser loops over. */
+export declare function argTypesFor(capability: string): readonly ArgTypeBindingV1[];
+export type ValueRead = {
+    ok: true;
+    value: string;
+}
+/** `said` is what the person or planner wrote, kept VERBATIM so a question can name it back. */
+ | {
+    ok: false;
+    said: string;
+    because: string;
+};
+/**
+ * Read one value of a declared type. TOTAL: it never throws and never guesses; an unreadable value comes
+ * back with the words that could not be read and a reason a person can act on.
+ */
+export declare function readValue(type: ValueTypeName, raw: unknown, opts?: {
+    assets?: readonly string[];
+}): ValueRead;
+/**
+ * IS THIS FLAG TRUE — the one reader for a yes/no, wherever it is read.
+ *
+ * `readValue('Flag', …)` canonicalises to the STRING "true"/"false", because every value a reader
+ * returns is a string and an argument that changed type on the way through would be worse. Consumers
+ * then have to parse it, and one of them compared to the BOOLEAN instead: `remove: true` arrived as
+ * `"true"`, the check failed, and asking to remove somebody from a household silently re-added them.
+ * One helper, so that comparison is written once.
+ */
+export declare function isFlagTrue(v: unknown): boolean;
+/** The kinds an `AgentKind` argument may be, for a surface that offers them rather than a box. */
+export declare function agentKindChoices(): Array<{
+    value: string;
+    label: string;
+}>;
+//# sourceMappingURL=arg-types.d.ts.map

package/dist/arg-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arg-types.d.ts","sourceRoot":"","sources":["../src/arg-types.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAKnE,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,OAAO,GAAG,cAAc,GAAG,cAAc,GAAG,MAAM,GAAG,WAAW,CAAC;AAExG,qGAAqG;AACrG,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,QAAQ,CAAC,CAOrE,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,aAAa,CAAC;IACpB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,SAAS,gBAAgB,EAiBhD,CAAC;AAEF;8GAC8G;AAC9G,wBAAgB,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAErF;AAED,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,gBAAgB,EAAE,CAE3E;AAED,MAAM,MAAM,SAAS,GACjB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AAC7B,gGAAgG;GAC9F;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAOjD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAAG,SAAS,CAkD7G;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAI9C;AAED,kGAAkG;AAClG,wBAAgB,gBAAgB,IAAI,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAE1E"}

package/dist/arg-types.js

@@ -0,0 +1,143 @@
+// WHAT AN ARGUMENT IS, AND HOW IT IS READ — spec 363 W2.
+//
+// `PARTY_ROLES` says what an argument's PARTY may be. This says what the rest of them ARE, and gives each
+// type exactly ONE reader — so a person's phrasing is understood identically in the normaliser, the
+// invoker and the form, and a refusal always names what it could not read.
+//
+// THE THREE INCIDENTS THIS TABLE EXISTS FOR, all in one week and all the same shape:
+//   · `amount: "20"` for "20 USDC" — a planner writing a REPRESENTATION it had no basis to compute.
+//     0.00002 dollars moved, under a mandate every gate approved.
+//   · "10 usdc" answered to "how much?" and silently dropped, because one branch wanted bare digits.
+//   · `wants ?? 'treasury'` — a kind with no declared value set, defaulting to the only one the code
+//     knew, so a team invitation asked somebody for a way to reach their treasury.
+//
+// A READER NEVER GUESSES. It returns the canonical value, or a refusal carrying the words it could not
+// read — which is what lets a question be asked ONCE more with the reason, rather than identically
+// forever.
+import { CLASS_FOR_SUFFIX } from './party-roles.js';
+const AP_VAL_NS = 'https://agenticprimitives.dev/ns/value#';
+const VAL = (local) => `${AP_VAL_NS}${local}`;
+/** The T-box term each type names. Checked by `check:ontology-bindings` like every other binding. */
+export const VALUE_TYPE_TERM = {
+    Amount: VAL('Amount'),
+    Asset: VAL('Asset'),
+    EmailAddress: VAL('EmailAddress'),
+    DisplayLabel: VAL('DisplayLabel'),
+    Flag: VAL('Flag'),
+    AgentKind: VAL('AgentKind'),
+};
+/**
+ * Every non-party argument, and what it is.
+ *
+ * PARTY ARGUMENTS ARE NOT HERE — they are in `PARTY_ROLES`, which answers a different question (which
+ * CLASS of agent may fill it, and which relation to follow to get there). One argument, one table.
+ */
+export const ARG_TYPES = [
+    { capability: 'treasury.payment.execute', arg: 'usdc', type: 'Amount', word: 'how much', hint: 'in whole USDC — "20", "12.50"' },
+    { capability: 'treasury.fund', arg: 'usdc', type: 'Amount', word: 'how much', hint: 'in whole USDC — "20", "12.50"' },
+    // `asset` IS NOT BOUND, deliberately. On a single-token deployment it is pinned from configuration and
+    // nobody — planner or person — may write it, so reading it would mean validating a value no caller
+    // supplies and, worse, ASKING about one: "which token?" is a question with exactly one answer that the
+    // system already knows. The `Asset` type stays declared for a deployment with a real choice to offer.
+    // THE ONE THAT SENT A TREASURY REQUEST TO SOMEBODY BEING INVITED TO A TEAM. A kind, with a declared
+    // value set and no default: not said ⇒ asked.
+    { capability: 'resolution.invitation.request', arg: 'wants', type: 'AgentKind', word: 'what you need', hint: 'a treasury (to send money), an organization, a team, or another agent of theirs' },
+    { capability: 'profile.contact.update', arg: 'email', type: 'EmailAddress', word: 'email', hint: 'in full, like name@example.org' },
+    { capability: 'profile.contact.update', arg: 'firstName', type: 'DisplayLabel', word: 'first name' },
+    { capability: 'profile.contact.update', arg: 'lastName', type: 'DisplayLabel', word: 'last name' },
+    { capability: 'household.member.record', arg: 'label', type: 'DisplayLabel', word: 'what you call them' },
+    { capability: 'household.member.record', arg: 'remove', type: 'Flag', word: 'remove them' },
+    { capability: 'treasury.primary.declare', arg: 'on', type: 'Flag', word: 'set it' },
+];
+/** The type bound to one capability's argument, or undefined — undefined means "not a value we read", and
+ *  the argument passes through untouched, which is how every unbound argument behaved before this existed. */
+export function argType(capability, arg) {
+    return ARG_TYPES.find((b) => b.capability === capability && b.arg === arg);
+}
+/** The value bindings of one capability — what a normaliser loops over. */
+export function argTypesFor(capability) {
+    return ARG_TYPES.filter((b) => b.capability === capability);
+}
+/** A placeholder is an omission, not a value — the planner's, and never quoted back at a person. */
+const PLACEHOLDER = /^<.*>$|^(unknown|tbd|n\/a|none|null|undefined|todo|xxx+)$/i;
+/** Control characters, by code point: a label is shown to people, and these are not shown to anyone. */
+const CONTROL_CHARS = new RegExp('[\\u0000-\\u001f\\u007f]', 'g');
+/**
+ * Read one value of a declared type. TOTAL: it never throws and never guesses; an unreadable value comes
+ * back with the words that could not be read and a reason a person can act on.
+ */
+export function readValue(type, raw, opts) {
+    const said = String(raw ?? '').trim();
+    if (!said || PLACEHOLDER.test(said))
+        return { ok: false, said: PLACEHOLDER.test(said) ? '' : said, because: 'nothing was given' };
+    switch (type) {
+        case 'Amount': {
+            // A currency word or symbol beside a figure adds no information a single-asset deployment does not
+            // already have; a thousands comma is punctuation. "10,50" stays unreadable rather than guessed at —
+            // a decimal comma and a thousands comma are the same character and only the person knows which.
+            const v = said.toLowerCase()
+                .replace(/^[$€£]/, '')
+                .replace(/\b(usdc|usd|dollars?|bucks?)\b/g, '')
+                .replace(/(\d),(?=\d{3}\b)/g, '$1')
+                .replace(/\s+/g, '');
+            return /^\d+(\.\d+)?$/.test(v)
+                ? { ok: true, value: v }
+                : { ok: false, said, because: 'that is not a figure I can read' };
+        }
+        case 'Asset': {
+            if (/^0x[0-9a-fA-F]{40}$/.test(said))
+                return { ok: true, value: said.toLowerCase() };
+            const known = (opts?.assets ?? []).map((a) => a.toLowerCase());
+            const sym = said.toLowerCase();
+            // A SYMBOL IS NOT AN ADDRESS. Only what this deployment configures resolves; a remembered address
+            // for another chain is well-formed and wrong, which is the failure that started this.
+            return known.includes(sym)
+                ? { ok: true, value: sym }
+                : { ok: false, said, because: 'this deployment does not have a token by that name' };
+        }
+        case 'EmailAddress':
+            return /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(said)
+                ? { ok: true, value: said }
+                : { ok: false, said, because: 'that is not an email address' };
+        case 'DisplayLabel': {
+            const clean = said.replace(CONTROL_CHARS, '').trim().slice(0, 120);
+            return clean ? { ok: true, value: clean } : { ok: false, said, because: 'that is not a name I can show' };
+        }
+        case 'Flag': {
+            const v = said.toLowerCase();
+            if (['true', 'yes', 'on', '1'].includes(v))
+                return { ok: true, value: 'true' };
+            if (['false', 'no', 'off', '0'].includes(v))
+                return { ok: true, value: 'false' };
+            return { ok: false, said, because: 'that is not a yes or a no' };
+        }
+        case 'AgentKind': {
+            const v = said.toLowerCase().replace(/^(a|an|the)\s+/, '').replace(/^their\s+/, '').trim();
+            // The vocabulary is the DERIVED AGENT TYPES (ADR-0061) — the same suffixes the naming service mints
+            // and `CLASS_FOR_SUFFIX` binds, never a second list that could disagree with them.
+            const suffixes = Object.keys(CLASS_FOR_SUFFIX);
+            const hit = suffixes.find((sfx) => sfx === v || `${sfx}s` === v || v.endsWith(` ${sfx}`));
+            return hit ? { ok: true, value: hit } : { ok: false, said, because: 'that is not a kind of agent I know' };
+        }
+    }
+}
+/**
+ * IS THIS FLAG TRUE — the one reader for a yes/no, wherever it is read.
+ *
+ * `readValue('Flag', …)` canonicalises to the STRING "true"/"false", because every value a reader
+ * returns is a string and an argument that changed type on the way through would be worse. Consumers
+ * then have to parse it, and one of them compared to the BOOLEAN instead: `remove: true` arrived as
+ * `"true"`, the check failed, and asking to remove somebody from a household silently re-added them.
+ * One helper, so that comparison is written once.
+ */
+export function isFlagTrue(v) {
+    if (v === true)
+        return true;
+    const read = readValue('Flag', v);
+    return read.ok && read.value === 'true';
+}
+/** The kinds an `AgentKind` argument may be, for a surface that offers them rather than a box. */
+export function agentKindChoices() {
+    return Object.keys(CLASS_FOR_SUFFIX).map((sfx) => ({ value: sfx, label: sfx }));
+}
+//# sourceMappingURL=arg-types.js.map

package/dist/arg-types.js.map

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

package/dist/artifacts.d.ts

@@ -5,8 +5,10 @@
  */
 export declare const ARTIFACTS: {
     readonly context: "context.jsonld";
-    readonly tbox: readonly ["tbox/core.ttl", "tbox/identity.ttl", "tbox/intents.ttl", "tbox/constraints.ttl", "tbox/resolution.ttl", "tbox/agreement.ttl", "tbox/payment.ttl", "tbox/fulfillment.ttl", "tbox/attestation.ttl", "tbox/skills.ttl", "tbox/geo.ttl", "tbox/content.ttl", "tbox/registry.ttl", "tbox/discovery.ttl", "tbox/trust.ttl", "tbox/security-exposure.ttl", "tbox/agent-resolution.ttl", "tbox/verification-receipt.ttl", "tbox/scope.ttl", "tbox/situation.ttl", "tbox/org.ttl", "tbox/familyoffice.ttl", "tbox/entitlement.ttl", "tbox/interaction.ttl", "tbox/messaging.ttl", "tbox/guidance.ttl", "tbox/actor-context.ttl", "tbox/context.ttl", "tbox/profile.ttl", "tbox/execution.ttl", "tbox/plan.ttl", "tbox/coordination.ttl", "tbox/engagement.ttl"];
-    readonly cbox: readonly ["cbox/canonical-agent-id-shape.shacl.ttl", "cbox/controlled-vocabularies.ttl", "cbox/skill-vocabulary.ttl", "cbox/geo-vocabulary.ttl", "cbox/scope-vocabulary.ttl", "cbox/content-vocabulary.ttl", "cbox/discovery-graph-shapes.shacl.ttl", "cbox/interaction-vocabulary.ttl", "cbox/familyoffice-vocabulary.ttl", "cbox/familyoffice-shapes.shacl.ttl", "cbox/consultation-shapes.shacl.ttl", "cbox/interaction-shapes.shacl.ttl", "cbox/skill-grounding-vocabulary.ttl", "cbox/guidance-vocabulary.ttl", "cbox/profile-facet-vocabulary.ttl", "cbox/agent-facet-shapes.shacl.ttl", "cbox/capability-catalog-shapes.shacl.ttl"];
+    /** Spec 389 — the JSON-LD context a run's provenance record (`run.provenance:<runRef>`) is written under. */
+    readonly runProvenanceContext: "run-provenance.jsonld";
+    readonly tbox: readonly ["tbox/core.ttl", "tbox/identity.ttl", "tbox/contact.ttl", "tbox/naming.ttl", "tbox/intents.ttl", "tbox/constraints.ttl", "tbox/resolution.ttl", "tbox/agreement.ttl", "tbox/payment.ttl", "tbox/fulfillment.ttl", "tbox/attestation.ttl", "tbox/skills.ttl", "tbox/geo.ttl", "tbox/content.ttl", "tbox/registry.ttl", "tbox/discovery.ttl", "tbox/trust.ttl", "tbox/security-exposure.ttl", "tbox/agent-resolution.ttl", "tbox/verification-receipt.ttl", "tbox/scope.ttl", "tbox/situation.ttl", "tbox/org.ttl", "tbox/familyoffice.ttl", "tbox/entitlement.ttl", "tbox/interaction.ttl", "tbox/messaging.ttl", "tbox/guidance.ttl", "tbox/actor-context.ttl", "tbox/context.ttl", "tbox/profile.ttl", "tbox/execution.ttl", "tbox/plan.ttl", "tbox/prov-imports.ttl", "tbox/coordination.ttl", "tbox/engagement.ttl", "tbox/card-projection.ttl"];
+    readonly cbox: readonly ["cbox/canonical-agent-id-shape.shacl.ttl", "cbox/controlled-vocabularies.ttl", "cbox/registry-vocabulary.ttl", "cbox/skill-vocabulary.ttl", "cbox/geo-vocabulary.ttl", "cbox/scope-vocabulary.ttl", "cbox/content-vocabulary.ttl", "cbox/discovery-graph-shapes.shacl.ttl", "cbox/interaction-vocabulary.ttl", "cbox/familyoffice-vocabulary.ttl", "cbox/familyoffice-shapes.shacl.ttl", "cbox/consultation-shapes.shacl.ttl", "cbox/interaction-shapes.shacl.ttl", "cbox/skill-grounding-vocabulary.ttl", "cbox/guidance-vocabulary.ttl", "cbox/profile-facet-vocabulary.ttl", "cbox/agent-facet-shapes.shacl.ttl", "cbox/capability-catalog-shapes.shacl.ttl", "cbox/org-team-shapes.shacl.ttl", "cbox/naming-registry-shapes.shacl.ttl", "cbox/run-provenance-shapes.shacl.ttl", "cbox/card-projection-shapes.shacl.ttl"];
     readonly mappings: readonly ["mappings/spine-standards.ttl", "mappings/agent-discovery-standards.ttl", "mappings/collaboration-profile.ttl", "mappings/collaboration-crosswalk-actors.ttl", "mappings/collaboration-crosswalk-organization.ttl", "mappings/collaboration-crosswalk-messaging.ttl", "mappings/collaboration-crosswalk-intent.ttl", "mappings/collaboration-crosswalk-skills.ttl", "mappings/collaboration-crosswalk-authority.ttl", "mappings/collaboration-crosswalk-protocols.ttl", "mappings/collaboration-crosswalk-guidance.ttl", "mappings/actor-context-standards.ttl", "mappings/commerce-engagement-crosswalk.ttl"];
 };
 /**

package/dist/artifacts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"AASA;;;;GAIG;AACH,eAAO,MAAM,SAAS;;;;;CA+GZ,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEzD"}
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"AASA;;;;GAIG;AACH,eAAO,MAAM,SAAS;;IAEpB,6GAA6G;;;;;CAmIrG,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEzD"}

package/dist/artifacts.js

@@ -12,10 +12,15 @@ import { fileURLToPath } from 'node:url';
  */
 export const ARTIFACTS = {
     context: 'context.jsonld',
+    /** Spec 389 — the JSON-LD context a run's provenance record (`run.provenance:<runRef>`) is written under. */
+    runProvenanceContext: 'run-provenance.jsonld',
     tbox: [
         // Phase-1 (identity + core)
         'tbox/core.ttl',
         'tbox/identity.ttl',
+        'tbox/contact.ttl',
+        // Typed agent naming — tld, contextual issuance, contextual reference (spec 346 §3/§11; ADR-0061)
+        'tbox/naming.ttl',
         // Phase-1.5 (v2 coordination substrate spine; spec 225 §11.5)
         'tbox/intents.ttl',
         'tbox/constraints.ttl',
@@ -65,14 +70,21 @@ export const ARTIFACTS = {
         'tbox/execution.ttl',
         // P-Plan grounding (spec 332 §4; closes spec-316 W5) — the plan trichotomy
         'tbox/plan.ttl',
+        // PROV-O terms the substrate EMITS, declared so shapes, bindings and A-box rows target something real (spec 389)
+        'tbox/prov-imports.ttl',
         // Coordination plane (spec 332 core subset; ADR-0054) — Endeavor / shared plan / participation
         'tbox/coordination.ttl',
         // Intent engagement plane (spec 336 W0 subset) — projections / probes / offers / mandates / receipts
         'tbox/engagement.ttl',
+        // Canonical profile / A2A Agent Card / projection / publication / external identity binding
+        // (spec 347 §11; ADR-0062) — a second module of the ap: core namespace.
+        'tbox/card-projection.ttl',
     ],
     cbox: [
         'cbox/canonical-agent-id-shape.shacl.ttl',
         'cbox/controlled-vocabularies.ttl',
+        // Registry admission checks / lifecycle event kinds / derived entry status (spec 346 §7)
+        'cbox/registry-vocabulary.ttl',
         // Generic skills + geo codelists — on-chain-bound kinds (lockstep, ADR-0009)
         'cbox/skill-vocabulary.ttl',
         'cbox/geo-vocabulary.ttl',
@@ -102,6 +114,16 @@ export const ARTIFACTS = {
         'cbox/agent-facet-shapes.shacl.ttl',
         // Capability catalog well-formedness, the anti-pattern axioms, and realization contracts
         'cbox/capability-catalog-shapes.shacl.ttl',
+        // Team affiliation / workspace / representation / responsibility shapes (spec 344 §4.6)
+        'cbox/org-team-shapes.shacl.ttl',
+        // Typed names, contextual issuance, workspace agent + registry agents, receipts, lifecycle log
+        // (spec 346 §11). Structure, never permission.
+        'cbox/naming-registry-shapes.shacl.ttl',
+        // Run provenance validity R1–R6 (spec 389 W2): what makes a run's PROV record evidence
+        'cbox/run-provenance-shapes.shacl.ttl',
+        // Public card metadata, projection provenance (eight digests), external bindings, the
+        // public/private disclosure boundary (spec 347 §11)
+        'cbox/card-projection-shapes.shacl.ttl',
     ],
     mappings: [
         'mappings/spine-standards.ttl',

package/dist/artifacts.js.map

@@ -1 +1 @@
-{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,EAAE;AACF,0EAA0E;AAC1E,8EAA8E;AAC9E,6EAA6E;AAC7E,yCAAyC;AAEzC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,OAAO,EAAE,gBAAgB;IACzB,IAAI,EAAE;QACJ,4BAA4B;QAC5B,eAAe;QACf,mBAAmB;QACnB,8DAA8D;QAC9D,kBAAkB;QAClB,sBAAsB;QACtB,qBAAqB;QACrB,oBAAoB;QACpB,kBAAkB;QAClB,sBAAsB;QACtB,sBAAsB;QACtB,4CAA4C;QAC5C,iBAAiB;QACjB,cAAc;QACd,kDAAkD;QAClD,kBAAkB;QAClB,oEAAoE;QACpE,mBAAmB;QACnB,oBAAoB;QACpB,gBAAgB;QAChB,4BAA4B;QAC5B,uFAAuF;QACvF,wFAAwF;QACxF,2BAA2B;QAC3B,8DAA8D;QAC9D,+BAA+B;QAC/B,yBAAyB;QACzB,gBAAgB;QAChB,oDAAoD;QACpD,oBAAoB;QACpB,cAAc;QACd,8EAA8E;QAC9E,4EAA4E;QAC5E,uBAAuB;QACvB,sBAAsB;QACtB,sBAAsB;QACtB,oBAAoB;QACpB,oFAAoF;QACpF,mBAAmB;QACnB,gEAAgE;QAChE,wBAAwB;QACxB,uFAAuF;QACvF,kBAAkB;QAClB,2FAA2F;QAC3F,2FAA2F;QAC3F,kBAAkB;QAClB,oFAAoF;QACpF,6FAA6F;QAC7F,iDAAiD;QACjD,oBAAoB;QACpB,2EAA2E;QAC3E,eAAe;QACf,+FAA+F;QAC/F,uBAAuB;QACvB,qGAAqG;QACrG,qBAAqB;KACtB;IACD,IAAI,EAAE;QACJ,yCAAyC;QACzC,kCAAkC;QAClC,6EAA6E;QAC7E,2BAA2B;QAC3B,yBAAyB;QACzB,0DAA0D;QAC1D,2BAA2B;QAC3B,oEAAoE;QACpE,6BAA6B;QAC7B,kEAAkE;QAClE,uCAAuC;QACvC,kDAAkD;QAClD,iCAAiC;QACjC,gFAAgF;QAChF,kCAAkC;QAClC,gGAAgG;QAChG,2EAA2E;QAC3E,oCAAoC;QACpC,oDAAoD;QACpD,oCAAoC;QACpC,gFAAgF;QAChF,mCAAmC;QACnC,uCAAuC;QACvC,qCAAqC;QACrC,8BAA8B;QAC9B,wFAAwF;QACxF,mCAAmC;QACnC,iDAAiD;QACjD,mCAAmC;QACnC,yFAAyF;QACzF,0CAA0C;KAC3C;IACD,QAAQ,EAAE;QACR,8BAA8B;QAC9B,wCAAwC;QACxC,wDAAwD;QACxD,oCAAoC;QACpC,6CAA6C;QAC7C,mDAAmD;QACnD,gDAAgD;QAChD,6CAA6C;QAC7C,6CAA6C;QAC7C,gDAAgD;QAChD,gDAAgD;QAChD,+CAA+C;QAC/C,yFAAyF;QACzF,sCAAsC;QACtC,uGAAuG;QACvG,4CAA4C;KAC7C;CACO,CAAC;AAEX;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,YAAoB;IAC/C,OAAO,aAAa,CAAC,IAAI,GAAG,CAAC,MAAM,YAAY,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACvE,CAAC"}
+{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"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"}

package/dist/contact-fields.d.ts

@@ -0,0 +1,28 @@
+export interface ContactFieldV1 {
+    /** The argument name an Ask, a form or a contract uses. */
+    arg: string;
+    /** The path inside the record the Home writes (`contact.firstName`, `contact.location.street`). */
+    path: string;
+    /** The T-box property it means. */
+    property: string;
+    /** The words for it. */
+    label: string;
+    /** For the planner and a form: what to put here. */
+    hint: string;
+    /** Location fields set the record's precision together (see `precisionOf`). */
+    location?: boolean;
+}
+export declare const CONTACT_FIELDS: readonly ContactFieldV1[];
+export declare const CONTACT_FIELD_ARGS: readonly string[];
+export declare function contactField(arg: string): ContactFieldV1 | undefined;
+/** The precision an address implies from what is filled — the Home's own rule, stated once. */
+export declare function precisionOf(loc: {
+    street?: string;
+    line2?: string;
+    postalCode?: string;
+    locality?: string;
+    region?: string;
+}): 'country' | 'region' | 'locality' | 'address';
+/** The record binding's property map, derived — so the binding and the field list cannot drift. */
+export declare const CONTACT_PROFILE_PROPERTIES: Readonly<Record<string, string>>;
+//# sourceMappingURL=contact-fields.d.ts.map

package/dist/contact-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contact-fields.d.ts","sourceRoot":"","sources":["../src/contact-fields.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,cAAc;IAC7B,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAC;IACZ,mGAAmG;IACnG,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,eAAO,MAAM,cAAc,EAAE,SAAS,cAAc,EAanD,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAAqC,CAAC;AACtF,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAsD;AAE3H,+FAA+F;AAC/F,wBAAgB,WAAW,CAAC,GAAG,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAK5K;AAED,mGAAmG;AACnG,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAuE,CAAC"}

package/dist/contact-fields.js

@@ -0,0 +1,38 @@
+// THE CONTACT PROFILE'S FIELDS, ONCE — spec 371 §2.2 (a record edit is shaped by the record).
+//
+// "Set street address to 2445 Walters Drive, Erie Colorado 80516" was refused with "I can't help with
+// that here" while "change my phone" worked. The Ask's edit tool, the invoker, the DO's write allow-list
+// and the SKILL.md contract each carried their own hand-kept list of fields, and "street" was in none.
+// This is the one list — each argument the Ask may take, where it lives in the record the Home writes
+// (`vault:impact-profile`: `contact.<field>` and `contact.location.<field>`), and the T-box property it
+// means. Every surface derives from it; a field added here is editable everywhere, described the same.
+const APCON = 'https://agenticprimitives.dev/ns/contact#';
+export const CONTACT_FIELDS = [
+    { arg: 'firstName', path: 'contact.firstName', property: `${APCON}givenName`, label: 'first name', hint: 'given name' },
+    { arg: 'lastName', path: 'contact.lastName', property: `${APCON}familyName`, label: 'last name', hint: 'family name' },
+    { arg: 'email', path: 'contact.email', property: `${APCON}email`, label: 'email', hint: 'an email address' },
+    { arg: 'phone', path: 'contact.phone', property: `${APCON}telephone`, label: 'phone', hint: 'a telephone number' },
+    { arg: 'organizationName', path: 'contact.organizationName', property: `${APCON}organizationName`, label: 'organization', hint: 'the organization they work with' },
+    { arg: 'organizationCountry', path: 'contact.organizationCountry', property: `${APCON}organizationCountry`, label: 'organization country', hint: 'where that organization is' },
+    { arg: 'street', path: 'contact.location.street', property: `${APCON}streetAddress`, label: 'street address', hint: 'street and number, e.g. "2445 Walters Drive"', location: true },
+    { arg: 'line2', path: 'contact.location.line2', property: `${APCON}streetAddressLine2`, label: 'address line 2', hint: 'apartment, suite or unit', location: true },
+    { arg: 'city', path: 'contact.location.locality', property: `${APCON}addressLocality`, label: 'city', hint: 'city or town, e.g. "Erie"', location: true },
+    { arg: 'region', path: 'contact.location.region', property: `${APCON}addressRegion`, label: 'state or province', hint: 'state or province, e.g. "Colorado"', location: true },
+    { arg: 'postalCode', path: 'contact.location.postalCode', property: `${APCON}postalCode`, label: 'postal code', hint: 'postal or ZIP code, e.g. "80516"', location: true },
+    { arg: 'country', path: 'contact.location.country', property: `${APCON}addressCountry`, label: 'country', hint: 'the country, e.g. "United States" — required for any finer address', location: true },
+];
+export const CONTACT_FIELD_ARGS = CONTACT_FIELDS.map((f) => f.arg);
+export function contactField(arg) { return CONTACT_FIELDS.find((f) => f.arg === arg); }
+/** The precision an address implies from what is filled — the Home's own rule, stated once. */
+export function precisionOf(loc) {
+    if (loc.street || loc.line2 || loc.postalCode)
+        return 'address';
+    if (loc.locality)
+        return 'locality';
+    if (loc.region)
+        return 'region';
+    return 'country';
+}
+/** The record binding's property map, derived — so the binding and the field list cannot drift. */
+export const CONTACT_PROFILE_PROPERTIES = Object.fromEntries(CONTACT_FIELDS.map((f) => [f.path, f.property]));
+//# sourceMappingURL=contact-fields.js.map

package/dist/contact-fields.js.map

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