@coasys/ad4m 0.13.0-test-interpretation → 0.13.0-test-interpretation-2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/lib/index.cjs +451 -149
  2. package/lib/index.js +449 -150
  3. package/lib/src/Literal.js +8 -0
  4. package/lib/src/generated/api/RunInterpretationRequest.d.ts +16 -0
  5. package/lib/src/model/Ad4mModel.d.ts +28 -11
  6. package/lib/src/model/Ad4mModel.js +57 -35
  7. package/lib/src/model/ModelQueryBuilder.js +2 -2
  8. package/lib/src/model/decorators.d.ts +52 -8
  9. package/lib/src/model/decorators.js +18 -8
  10. package/lib/src/model/json-schema.js +7 -21
  11. package/lib/src/model/query-common.d.ts +2 -2
  12. package/lib/src/model/query-sparql.d.ts +62 -0
  13. package/lib/src/model/query-sparql.js +78 -15
  14. package/lib/src/model/query-utils.d.ts +7 -2
  15. package/lib/src/model/query-utils.js +21 -11
  16. package/lib/src/model/shacl-gen.js +44 -15
  17. package/lib/src/model/types.d.ts +23 -8
  18. package/lib/src/perspectives/AutoProcessor.d.ts +132 -2
  19. package/lib/src/perspectives/InterpretationModels.d.ts +51 -3
  20. package/lib/src/perspectives/InterpretationModels.js +64 -26
  21. package/lib/src/perspectives/PerspectiveClient.d.ts +22 -2
  22. package/lib/src/perspectives/PerspectiveClient.js +35 -3
  23. package/lib/src/perspectives/PerspectiveProxy.d.ts +9 -1
  24. package/lib/src/perspectives/PerspectiveProxy.js +24 -14
  25. package/lib/src/perspectives/SparqlBindings.d.ts +24 -3
  26. package/lib/src/perspectives/SparqlBindings.js +57 -6
  27. package/lib/src/shacl/SHACLShape.d.ts +11 -3
  28. package/lib/src/shacl/SHACLShape.js +15 -1
  29. package/lib/src/shacl/index.d.ts +1 -1
  30. package/lib/src/shacl/index.js +1 -1
  31. package/package.json +2 -2
  32. package/src/Literal.ts +7 -0
  33. package/src/generated/api/RunInterpretationRequest.ts +19 -3
  34. package/src/model/Ad4mModel.test.ts +84 -22
  35. package/src/model/Ad4mModel.ts +61 -41
  36. package/src/model/ModelQueryBuilder.ts +2 -2
  37. package/src/model/decorators.ts +62 -9
  38. package/src/model/json-schema.ts +10 -25
  39. package/src/model/query-common.ts +2 -2
  40. package/src/model/query-sparql.test.ts +114 -13
  41. package/src/model/query-sparql.ts +83 -14
  42. package/src/model/query-utils.ts +22 -12
  43. package/src/model/shacl-gen.ts +42 -13
  44. package/src/model/shacl-roundtrip.test.ts +4 -2
  45. package/src/model/types.ts +23 -8
  46. package/src/perspectives/AutoProcessor.ts +133 -1
  47. package/src/perspectives/InterpretationModels.ts +103 -21
  48. package/src/perspectives/PerspectiveClient.ts +50 -4
  49. package/src/perspectives/PerspectiveProxy.ts +37 -21
  50. package/src/perspectives/SparqlBindings.test.ts +134 -0
  51. package/src/perspectives/SparqlBindings.ts +57 -6
  52. package/src/shacl/SHACLShape.test.ts +56 -4
  53. package/src/shacl/SHACLShape.ts +30 -6
  54. package/src/shacl/index.ts +1 -1
@@ -3,7 +3,55 @@
3
3
  // `AutoProcessorConfig` / `auto_processor::events::AutoProcessorEvent`
4
4
  // (serde `camelCase`).
5
5
 
6
- /** One step in an auto-processor pass (serde camelCase of the Rust enum). */
6
+ /**
7
+ * Raw form of `Scope` (parent node + linking predicate) — the only variant
8
+ * the WebSocket auto-processor config accepts. `Scope`'s model form
9
+ * (`{ model: typeof Ad4mModel, id, field? }`) references a JS class
10
+ * constructor, which JSON.stringify silently drops, so the executor would
11
+ * receive `{ id }` and the scope would be unresolvable. Client callers who
12
+ * hold a model class should resolve its predicate via
13
+ * `ModelQueryBuilder.buildParentScope()` first and pass the result here.
14
+ */
15
+ export type RawScope = { id: string; predicate: string };
16
+
17
+ /**
18
+ * One step in an auto-processor pass (serde camelCase of the Rust enum).
19
+ *
20
+ * ## Lifecycle (winning peer, emitDebugEvents: true)
21
+ *
22
+ * A pass on the winning executor emits, in order:
23
+ *
24
+ * 1. `batchReady` — debounced batch reached threshold, pass starting
25
+ * 2. `claimed` — this executor won the `try_claim`
26
+ * 3. `gatheringTranscript` — pulling the batch's transcript turns
27
+ * 4. `runningInterpretation` — about to invoke the LLM
28
+ * 5. `llmRequestSent` — prompt built + dispatched; carries `llmInput`
29
+ * (only when `emitDebugEvents: true`)
30
+ * 6. `llmResponseReceived` — LLM response arrived; carries `llmOutput`
31
+ * (only when `emitDebugEvents: true`) — the UI
32
+ * can render "waiting on LLM" between steps 5-6
33
+ * 7. `processed` — pass complete; carries `bases[]` (new/updated
34
+ * instance URIs)
35
+ *
36
+ * ## Lifecycle (losing peer, or short-circuit)
37
+ *
38
+ * - `batchReady` → `backedOff` — another peer claimed the batch first
39
+ * - `batchReady` → `awaitingAuthor` — no author of the batch is online
40
+ * - `batchReady` → `notCandidate` — this peer stood down for an earlier author
41
+ * - `claimed` → `shapesMissing` — a configured class shape hasn't synced
42
+ * - `claimed` → `emptyTranscript` — the batch drained empty
43
+ *
44
+ * ## Payload fields per step
45
+ *
46
+ * All steps carry `perspectiveUuid`, `processorId`, `agentDid`, `itemIds[]`.
47
+ * Additional payload:
48
+ *
49
+ * - `backedOff`, `notCandidate` → `detail` = holder / elected-author DID
50
+ * - `shapesMissing` → `detail` = comma-joined missing class URIs
51
+ * - `llmRequestSent` → `llmInput` = raw prompt
52
+ * - `llmResponseReceived` → `llmOutput` = raw LLM response
53
+ * - `processed` → `bases[]` = new/updated instance URIs
54
+ */
7
55
  export type AutoProcessorStep =
8
56
  | "batchReady"
9
57
  | "claimed"
@@ -12,6 +60,8 @@ export type AutoProcessorStep =
12
60
  | "notCandidate"
13
61
  | "gatheringTranscript"
14
62
  | "runningInterpretation"
63
+ | "llmRequestSent"
64
+ | "llmResponseReceived"
15
65
  | "processed"
16
66
  | "shapesMissing"
17
67
  | "emptyTranscript";
@@ -30,6 +80,46 @@ export interface AutoProcessorEvent {
30
80
  bases: string[];
31
81
  /** Free-form context for the step (a holder/elected DID, an error, …). */
32
82
  detail?: string;
83
+ /** Raw LLM prompt this pass fed the model. Present ONLY on
84
+ * `llmRequestSent` events, and only when the processor was configured
85
+ * with `emitDebugEvents: true`. Never carried on `processed`. */
86
+ llmInput?: string;
87
+ /** Raw LLM response this pass received. Present ONLY on
88
+ * `llmResponseReceived` events, and only when the processor was
89
+ * configured with `emitDebugEvents: true`. Never carried on `processed`. */
90
+ llmOutput?: string;
91
+ }
92
+
93
+ /**
94
+ * Coarse-grained phase of a neighbourhood-state event.
95
+ *
96
+ * `claimed` — this executor just started a pass.
97
+ * `finished` — the pass completed successfully.
98
+ * `abandoned` — the pass short-circuited (missing shape / empty batch /
99
+ * error); the claim will TTL-expire.
100
+ */
101
+ export type NeighbourhoodPhase = "claimed" | "finished" | "abandoned";
102
+
103
+ /**
104
+ * `auto-processor-neighbourhood-state` — perspective-scoped observability
105
+ * event. Fires when THIS executor claims, finishes, or abandons a batch.
106
+ * Anyone with perspective read access sees it, so a UI can render "someone
107
+ * is auto-processing this" without receiving the batch payload or LLM I/O.
108
+ *
109
+ * Cross-executor visibility (peer's claim reaching us via Holochain sync) is
110
+ * NOT covered here; consumers who need that subscribe to `link-added` and
111
+ * filter for the `has_claim` predicate on the shared perspective.
112
+ */
113
+ export interface AutoProcessorNeighbourhoodStateEvent {
114
+ type: "auto-processor-neighbourhood-state";
115
+ perspectiveUuid: string;
116
+ processorId: string;
117
+ /** DID that claimed the batch — the pass owner's DID. */
118
+ claimantDid: string;
119
+ /** SHA-256 hex of the batch's item-id set — merge `claimed` + `finished`
120
+ * for the same key to render a single row in a UI. */
121
+ batchKey: string;
122
+ phase: NeighbourhoodPhase;
33
123
  }
34
124
 
35
125
  /** Configuration for `perspective.addAutoProcessor` (everything but `uuid`). */
@@ -86,6 +176,48 @@ export interface AddAutoProcessorConfig {
86
176
  * runs.
87
177
  */
88
178
  sourceWindowMs?: number;
179
+ /**
180
+ * Optional parent-scope filter for the dedup lookup: when set, only
181
+ * existing instances of the interpretation classes that live under this
182
+ * scope are candidates for upsert. Omit for the whole-perspective dedup
183
+ * set (pre-scope behaviour). Raw form only — see `RawScope`.
184
+ */
185
+ existingScope?: RawScope;
186
+ /**
187
+ * Optional parent-scope target for newly minted instances: when set,
188
+ * every base URI the pass CREATES is additionally linked as a child of
189
+ * `mintScope.id` via the scope's predicate — turning the SoA-tree
190
+ * "children live under this node" pattern from a URI-prefix convention
191
+ * into an actual graph edge. Upserts of pre-existing instances are NOT
192
+ * linked (would multi-parent unrelated graph state). Raw form only —
193
+ * see `RawScope`; the Rust watcher rejects `Model` scopes at runtime.
194
+ */
195
+ mintScope?: RawScope;
196
+ /**
197
+ * Persist the raw LLM prompt + response on the pass's `InterpretationRun`
198
+ * (`debugPrompt` / `debugResponse`) so a UI can look them up post-hoc.
199
+ * Independent of `emitDebugEvents` — Nico's PR #903 split so a caller
200
+ * can persist without emitting mid-pass events (retrospective inspection
201
+ * only) or emit without persisting (live observability, no graph-sync
202
+ * payload). Default `false` — LLM I/O is 10s of KB per pass and every
203
+ * enabled peer syncs it.
204
+ */
205
+ persistDebug?: boolean;
206
+ /**
207
+ * Emit `LlmRequestSent` and `LlmResponseReceived` `auto-processor-event`s
208
+ * mid-pass, so a subscribed UI can render "waiting on LLM" between
209
+ * prompt-send and response-receive. See `persistDebug` for the split
210
+ * rationale. Default `false`.
211
+ */
212
+ emitDebugEvents?: boolean;
213
+ /**
214
+ * Legacy backwards-compat alias — pre-split callers set `debugMode` as a
215
+ * single coupled flag. When present and both `persistDebug` +
216
+ * `emitDebugEvents` are absent, its value is expanded to both. The two
217
+ * specific fields take precedence when present. Prefer the split fields;
218
+ * this alias is retained so pre-split clients still work.
219
+ */
220
+ debugMode?: boolean;
89
221
  }
90
222
 
91
223
  /**
@@ -16,7 +16,7 @@
16
16
  */
17
17
 
18
18
  import { Ad4mModel } from "../model/Ad4mModel";
19
- import { Flag, HasMany, Optional, Property } from "../model/decorators";
19
+ import { HasMany, Optional, Property } from "../model/decorators";
20
20
  import { Model } from "../model/decorators";
21
21
 
22
22
  // ── AutoProcessorConfig ─────────────────────────────────────────────────────
@@ -24,12 +24,19 @@ import { Model } from "../model/decorators";
24
24
  // One node per registered processor; the node URI is
25
25
  // `ad4m://autoprocessor/<processorId>`.
26
26
 
27
- @Model({ name: "AutoProcessorConfig" })
27
+ // Model name = "AutoProcessor" (NOT "AutoProcessorConfig") to match the Rust
28
+ // hardwired subject class in `perspectives/auto_processor/config.rs` — that
29
+ // alignment is what the SDNA parity test in
30
+ // `tests/js/tests/model/interpretation-models.test.ts` guards. The TS class
31
+ // symbol keeps the `Config` suffix for readability (`AutoProcessorConfig` reads
32
+ // better than a bare `AutoProcessor` for an "instances of the config record"
33
+ // query), but the on-graph subject class it registers is `AutoProcessor`.
34
+ @Model({ name: "AutoProcessor" })
28
35
  export class AutoProcessorConfig extends Ad4mModel {
29
- @Flag({ through: "rdf://type", value: "ad4m://AutoProcessor" })
30
- type: string = "ad4m://AutoProcessor";
31
-
32
36
  /** Unique processor id — the dedup key for auto-processor instances. */
37
+ // First-declared property: `buildSHACL` derives the shape namespace from
38
+ // its `through` prefix, so `ad4m://processor_id` → `ad4m://` → target_class
39
+ // `ad4m://AutoProcessor` (matches Rust `AUTO_PROCESSOR_TARGET_CLASS`).
33
40
  @Property({ through: "ad4m://processor_id", required: true, identity: true })
34
41
  processorId: string = "";
35
42
 
@@ -38,11 +45,15 @@ export class AutoProcessorConfig extends Ad4mModel {
38
45
  sourceScopeQuery: string = "";
39
46
 
40
47
  /** URI prefix for minted instances; omit for the per-processor default. */
41
- @Optional({ through: "ad4m://base_prefix", resolveLanguage: "literal" })
48
+ // No resolveLanguage — Rust SDNA declares none for this property, so under
49
+ // PR #874 both sides get the fast deterministic typed-literal path.
50
+ // (resolveLanguage: "literal" would ask the executor for a signed envelope
51
+ // that the Rust writer never produces for config metadata.)
52
+ @Optional({ through: "ad4m://base_prefix" })
42
53
  basePrefix?: string;
43
54
 
44
55
  /** Class URIs (SHACL targetClass) to materialise each pass. */
45
- @HasMany({ through: "ad4m://interpretation_class" })
56
+ @HasMany({ through: "ad4m://interpretation_class", datatype: "xsd:string" })
46
57
  interpretationClasses: string[] = [];
47
58
 
48
59
  /** Quiet-window (ms) after the last new item before a pass runs. */
@@ -50,7 +61,7 @@ export class AutoProcessorConfig extends Ad4mModel {
50
61
  debounceMs: string = "200";
51
62
 
52
63
  /** Minimum batch size before a pass runs (default 1). */
53
- @Optional({ through: "ad4m://batch_min", resolveLanguage: "literal" })
64
+ @Optional({ through: "ad4m://batch_min" })
54
65
  batchMin?: string;
55
66
 
56
67
  /** Maximum items per pass. */
@@ -58,7 +69,7 @@ export class AutoProcessorConfig extends Ad4mModel {
58
69
  batchMax: string = "32";
59
70
 
60
71
  /** Safety flush (ms) for a sub-`batchMin` batch; absent = wait indefinitely. */
61
- @Optional({ through: "ad4m://max_wait_ms", resolveLanguage: "literal" })
72
+ @Optional({ through: "ad4m://max_wait_ms" })
62
73
  maxWaitMs?: string;
63
74
 
64
75
  /** How long a won claim is authoritative before peers may re-claim (ms). */
@@ -66,12 +77,70 @@ export class AutoProcessorConfig extends Ad4mModel {
66
77
  claimTtlMs: string = "60000";
67
78
 
68
79
  /** How far back (ms) each pass looks; absent = unbounded. */
69
- @Optional({ through: "ad4m://source_window_ms", resolveLanguage: "literal" })
80
+ @Optional({ through: "ad4m://source_window_ms" })
70
81
  sourceWindowMs?: string;
71
82
 
72
83
  /** Serialised `DedupStrategy` JSON (absent = NormalizedString). */
73
- @Optional({ through: "ad4m://dedup_strategy", resolveLanguage: "literal" })
84
+ @Optional({ through: "ad4m://dedup_strategy" })
74
85
  dedupStrategy?: string;
86
+
87
+ /**
88
+ * Serialised `Scope` JSON (absent = whole-perspective dedup set).
89
+ * Constrains the existing-instance lookup to the subtree rooted at
90
+ * `Scope.id` linked via `Scope.predicate` — the SoA-tree "existing items
91
+ * live under THIS project node" pattern. Stored as an opaque JSON blob
92
+ * because SHACL properties carry no rich-object type-check; the Rust
93
+ * watcher parses it back into `Scope`.
94
+ */
95
+ @Optional({ through: "ad4m://existing_scope" })
96
+ existingScope?: string;
97
+
98
+ /**
99
+ * Serialised `Scope` JSON (absent = mint sites are unlinked). When set,
100
+ * every freshly created base URI gets an additional `Scope.id
101
+ * --Scope.predicate--> new-uri` link written into the perspective, so
102
+ * mints become first-class children of the target scope. Must be the
103
+ * `Raw` form of `Scope`; `Model` scopes carry no linking predicate.
104
+ */
105
+ @Optional({ through: "ad4m://mint_scope" })
106
+ mintScope?: string;
107
+
108
+ /**
109
+ * Legacy coupled debug knob (`"true"` / `"false"` string). Reserved as a
110
+ * backwards-compat scalar: pre-split writes used it as the single flag
111
+ * for both LLM I/O persistence AND mid-pass event emission. The Rust
112
+ * loader still reads it as a fallback when the specific `persistDebug`
113
+ * / `emitDebugEvents` fields are absent. New writes SHOULD prefer the
114
+ * split fields (below); this alias is retained so a pre-split peer's
115
+ * config still loads with the coupled behaviour it originally requested.
116
+ */
117
+ @Optional({ through: "ad4m://debug_mode", resolveLanguage: "literal" })
118
+ debugMode?: string;
119
+
120
+ /**
121
+ * Persist the raw LLM prompt + response on the pass's `InterpretationRun`
122
+ * (`debugPrompt` / `debugResponse`). Independent of `emitDebugEvents`
123
+ * — Nico's PR #903 split. Absent = fall back to legacy `debugMode` (see
124
+ * above); when both are absent, defaults to `"false"`.
125
+ */
126
+ @Optional({ through: "ad4m://persist_debug", resolveLanguage: "literal" })
127
+ persistDebug?: string;
128
+
129
+ /**
130
+ * Emit `LlmRequestSent` and `LlmResponseReceived` auto-processor events
131
+ * mid-pass, so a subscribed UI can render "waiting on LLM" between
132
+ * prompt-send and response-receive. Independent of `persistDebug`.
133
+ * Absent = fall back to legacy `debugMode`; when both are absent,
134
+ * defaults to `"false"`.
135
+ */
136
+ @Optional({ through: "ad4m://emit_debug_events", resolveLanguage: "literal" })
137
+ emitDebugEvents?: string;
138
+
139
+ // No `@Flag` type discriminator (Nico 2026-08-19: "type flags are an
140
+ // anti-pattern for subject classes; match over all the properties
141
+ // instead"). Conformance is by the presence of `processorId` +
142
+ // `sourceScopeQuery` + `interpretationClasses` + `debounceMs` +
143
+ // `batchMax` + `claimTtlMs` — the Rust SDNA takes the same shape.
75
144
  }
76
145
 
77
146
  // ── InterpretationRun ───────────────────────────────────────────────────────
@@ -80,36 +149,49 @@ export class AutoProcessorConfig extends Ad4mModel {
80
149
 
81
150
  @Model({ name: "InterpretationRun" })
82
151
  export class InterpretationRun extends Ad4mModel {
83
- @Flag({ through: "ad4m://type", value: "ad4m://interpretation-run" })
84
- type: string = "ad4m://interpretation-run";
152
+ // No `@Flag` type discriminator — Rust SDNA drops `ad4m://type` too.
153
+ // Conformance is by `runId` (identity) — same pattern
154
+ // `InterpretationOverlay` already uses (`kind` is its discriminator).
85
155
 
86
156
  /** UUID for this run — the dedup key across run nodes. */
87
157
  @Property({ through: "ad4m://interp/run_id", required: true, identity: true })
88
158
  runId: string = "";
89
159
 
90
160
  /** LLM model id used for this run. */
91
- @Optional({ through: "ad4m://interp/model", resolveLanguage: "literal" })
161
+ @Optional({ through: "ad4m://interp/model" })
92
162
  model?: string;
93
163
 
94
164
  /** SHA-256 hex of the system prompt + few-shots at the time of the run. */
95
- @Optional({ through: "ad4m://interp/prompt_version", resolveLanguage: "literal" })
165
+ @Optional({ through: "ad4m://interp/prompt_version" })
96
166
  promptVersion?: string;
97
167
 
98
168
  /** RFC3339 timestamp when the run completed. */
99
- @Optional({ through: "ad4m://interp/ran_at", resolveLanguage: "literal" })
169
+ @Optional({ through: "ad4m://interp/ran_at" })
100
170
  ranAt?: string;
101
171
 
102
172
  /** URI of the AutoProcessorConfig node that triggered this run. */
103
- @Optional({ through: "ad4m://interp/processor", resolveLanguage: "literal" })
173
+ @Optional({ through: "ad4m://interp/processor" })
104
174
  processor?: string;
105
175
 
106
176
  /**
107
177
  * Source item IDs consumed by this pass.
108
178
  * Stored as multiple links with the same predicate; the processed-turn
109
- * cursor uses these to avoid re-interpreting a turn.
179
+ * cursor uses these to avoid re-interpreting a turn. Values are plain
180
+ * strings (turn hex), so the property opts into `sh:datatype`-gated
181
+ * literal decoding on hydration.
110
182
  */
111
- @HasMany({ through: "ad4m://interp/sources" })
183
+ @HasMany({ through: "ad4m://interp/sources", datatype: "xsd:string" })
112
184
  sources: string[] = [];
185
+
186
+ /** Raw LLM prompt this pass fed the model. Present only when the pass's
187
+ * AutoProcessor had `persistDebug: true` (or the legacy `debugMode: true`
188
+ * fallback). Absent by default. */
189
+ @Optional({ through: "ad4m://interp/debug_prompt", resolveLanguage: "literal" })
190
+ debugPrompt?: string;
191
+
192
+ /** Raw LLM response this pass received. Same rules as `debugPrompt`. */
193
+ @Optional({ through: "ad4m://interp/debug_response", resolveLanguage: "literal" })
194
+ debugResponse?: string;
113
195
  }
114
196
 
115
197
  // ── InterpretationOverlay ───────────────────────────────────────────────────
@@ -136,10 +218,10 @@ export class InterpretationOverlay extends Ad4mModel {
136
218
  * changes to an existing one (`"update"`). This is the discriminator link
137
219
  * that makes a node identifiable as an overlay.
138
220
  */
139
- @Property({ through: "ad4m://interp/kind", required: true, resolveLanguage: "literal" })
221
+ @Property({ through: "ad4m://interp/kind", required: true })
140
222
  kind: string = "";
141
223
 
142
224
  /** URI of the InterpretationRun that last wrote this overlay, if present. */
143
- @Optional({ through: "ad4m://interp/run", resolveLanguage: "literal" })
225
+ @Optional({ through: "ad4m://interp/run" })
144
226
  run?: string;
145
227
  }
@@ -11,7 +11,7 @@ import { LinkStatus, PerspectiveProxy } from './PerspectiveProxy';
11
11
  import { AIClient } from "../ai/AIClient";
12
12
  import { AllInstancesResult } from "../model/types";
13
13
  import type { TranscriptTurn } from "../generated/api";
14
- import type { AddAutoProcessorConfig, AutoProcessorEvent, InterpretationOverlayInfo } from "./AutoProcessor";
14
+ import type { AddAutoProcessorConfig, AutoProcessorEvent, AutoProcessorNeighbourhoodStateEvent, InterpretationOverlayInfo, RawScope } from "./AutoProcessor";
15
15
 
16
16
  export type PerspectiveHandleCallback = (perspective: PerspectiveHandle) => null
17
17
  export type UuidCallback = (uuid: string) => null
@@ -261,11 +261,25 @@ export class PerspectiveClient {
261
261
  * retries on parse failure), so it can legitimately take minutes on slower
262
262
  * or CPU-only models. We raise the default 30s RPC timeout here to 20 min
263
263
  * (matches the CI `--timeout 1200000` for the interpretation tests).
264
+ *
265
+ * `existingScope` and `mintScope` match the AutoProcessor semantics:
266
+ * `existingScope` constrains the dedup lookup to instances under a
267
+ * subtree; `mintScope` links every FRESHLY-created base as a child of
268
+ * `mintScope.id` via its predicate (upserts of pre-existing instances
269
+ * are NOT re-parented — same rule as the watcher).
264
270
  */
265
- async runInterpretation(uuid: string, transcript: TranscriptTurn[], basePrefix: string, classes?: string[]): Promise<string[]> {
271
+ async runInterpretation(
272
+ uuid: string,
273
+ transcript: TranscriptTurn[],
274
+ basePrefix: string,
275
+ classes?: string[],
276
+ existingScope?: RawScope,
277
+ mintScope?: RawScope,
278
+ ): Promise<string[]> {
266
279
  const RUN_INTERPRETATION_TIMEOUT_MS = 20 * 60 * 1000
267
280
  return this.#apiClient.call<string[]>(
268
- 'perspective.runInterpretation', { uuid, transcript, basePrefix, classes },
281
+ 'perspective.runInterpretation',
282
+ { uuid, transcript, basePrefix, classes, existingScope, mintScope },
269
283
  RUN_INTERPRETATION_TIMEOUT_MS,
270
284
  )
271
285
  }
@@ -311,6 +325,11 @@ export class PerspectiveClient {
311
325
  * Subscribe to auto-processor step signals. `cb` fires for every
312
326
  * `auto-processor-event` on `uuid` (BatchReady → Claimed/BackedOff/… →
313
327
  * Processed), letting a UI show progress and await the next batch.
328
+ *
329
+ * Registered on the per-uuid `#linkUnsubscribers` map so
330
+ * `PerspectiveProxy.dispose()` → `removeAllListeners(uuid)` cleans the
331
+ * subscription up; using the global `#unsubscribers` array would leak
332
+ * callbacks across repeated view lifecycles (CodeRabbit #881 review).
314
333
  */
315
334
  async addAutoProcessorEventListener(uuid: String, cb: (event: AutoProcessorEvent) => void): Promise<void> {
316
335
  const unsub = this.#apiClient.subscribe(
@@ -320,7 +339,34 @@ export class PerspectiveClient {
320
339
  }
321
340
  }
322
341
  )
323
- this.#unsubscribers.push(unsub)
342
+ let existing = this.#linkUnsubscribers.get(uuid as string) || []
343
+ existing.push(unsub)
344
+ this.#linkUnsubscribers.set(uuid as string, existing)
345
+ await this.#apiClient.waitForSubscription()
346
+ }
347
+
348
+ /**
349
+ * Subscribe to neighbourhood-state events on a perspective. `cb` fires
350
+ * when THIS executor claims / finishes / abandons a batch for any
351
+ * processor on `uuid` — perspective-scoped observability so a UI can
352
+ * render "someone is auto-processing this" without receiving the batch
353
+ * payload or LLM I/O. Registered on the per-uuid `#linkUnsubscribers`
354
+ * map so `PerspectiveProxy.dispose()` sweeps it up.
355
+ */
356
+ async addAutoProcessorNeighbourhoodStateListener(
357
+ uuid: String,
358
+ cb: (event: AutoProcessorNeighbourhoodStateEvent) => void,
359
+ ): Promise<void> {
360
+ const unsub = this.#apiClient.subscribe(
361
+ (data) => {
362
+ if (data.type === 'auto-processor-neighbourhood-state' && data.perspectiveUuid === uuid) {
363
+ cb(data as unknown as AutoProcessorNeighbourhoodStateEvent)
364
+ }
365
+ }
366
+ )
367
+ let existing = this.#linkUnsubscribers.get(uuid as string) || []
368
+ existing.push(unsub)
369
+ this.#linkUnsubscribers.set(uuid as string, existing)
324
370
  await this.#apiClient.waitForSubscription()
325
371
  }
326
372
 
@@ -16,7 +16,7 @@ import type { TranscriptTurn } from "../generated/api";
16
16
 
17
17
  import { SHACLShape } from "../shacl/SHACLShape";
18
18
  import { SHACLFlow, LinkPattern } from "../shacl/SHACLFlow";
19
- import type { AddAutoProcessorConfig, AutoProcessorEvent, InterpretationOverlayInfo } from "./AutoProcessor";
19
+ import type { AddAutoProcessorConfig, AutoProcessorEvent, AutoProcessorNeighbourhoodStateEvent, InterpretationOverlayInfo } from "./AutoProcessor";
20
20
 
21
21
  type QueryCallback = (result: AllInstancesResult) => void;
22
22
 
@@ -606,6 +606,19 @@ export class PerspectiveProxy {
606
606
  return await this.#client.addAutoProcessorEventListener(this.#handle.uuid, cb)
607
607
  }
608
608
 
609
+ /**
610
+ * Subscribe to this perspective's auto-processor neighbourhood-state
611
+ * events — fires when this executor claims / finishes / abandons a
612
+ * batch. Perspective-scoped, so a UI can render "someone is
613
+ * auto-processing this" without receiving the batch payload. See
614
+ * `AutoProcessorNeighbourhoodStateEvent`.
615
+ */
616
+ async addAutoProcessorNeighbourhoodStateListener(
617
+ cb: (event: AutoProcessorNeighbourhoodStateEvent) => void,
618
+ ): Promise<void> {
619
+ return await this.#client.addAutoProcessorNeighbourhoodStateListener(this.#handle.uuid, cb)
620
+ }
621
+
609
622
  /**
610
623
  * Executes a Prolog query against the perspective's knowledge base.
611
624
  * This is a powerful way to find complex patterns in the graph.
@@ -1522,36 +1535,39 @@ export class PerspectiveProxy {
1522
1535
  */
1523
1536
  async getFlow(name: string): Promise<SHACLFlow | null> {
1524
1537
  const flowNameLiteral = Literal.from(name).toUrl();
1525
-
1538
+
1526
1539
  // Find flow URI from name mapping
1527
1540
  const flowUriLinks = await this.get(new LinkQuery({
1528
1541
  source: flowNameLiteral,
1529
1542
  predicate: "ad4m://flow_uri"
1530
1543
  }));
1531
-
1544
+
1532
1545
  if (flowUriLinks.length === 0) {
1533
1546
  return null;
1534
1547
  }
1535
-
1548
+
1536
1549
  const flowUri = flowUriLinks[0].data.target;
1537
- // Compute alternate prefix for state/transition URIs
1538
- const alternatePrefix = flowUri.endsWith('Flow')
1539
- ? flowUri.slice(0, -4) + '.'
1540
- : flowUri + '.';
1541
-
1542
- // Fetch flow links using SPARQL to match flowUri source OR alternatePrefix sources
1543
- const sparqlQuery = `SELECT ?s ?p ?o WHERE {
1544
- ?s ?p ?o .
1545
- FILTER(?s = <${flowUri}> || STRSTARTS(STR(?s), "${alternatePrefix}"))
1546
- }`;
1547
- const sparqlResult = await this.querySparql(sparqlQuery);
1548
-
1549
- const flowLinks = (sparqlResult || []).map((r: any) => ({
1550
- source: r.s,
1551
- predicate: r.p,
1552
- target: r.o
1550
+
1551
+ // Fetch flow-level links (hasState, hasTransition, flowable, startAction)
1552
+ const flowLevelLinks = await this.get(new LinkQuery({ source: flowUri }));
1553
+
1554
+ // Collect state and transition URIs, then fetch their child links
1555
+ const childUris = flowLevelLinks
1556
+ .filter(l => l.data.predicate === "ad4m://hasState"
1557
+ || l.data.predicate === "ad4m://hasTransition")
1558
+ .map(l => l.data.target);
1559
+ const childResults = await Promise.all(
1560
+ childUris.map(uri => this.get(new LinkQuery({ source: uri })))
1561
+ );
1562
+
1563
+ // Flatten into the {source, predicate, target} shape fromLinks expects
1564
+ const allExprs = [...flowLevelLinks, ...childResults.flat()];
1565
+ const flowLinks = allExprs.map(l => ({
1566
+ source: l.data.source,
1567
+ predicate: l.data.predicate,
1568
+ target: l.data.target
1553
1569
  }));
1554
-
1570
+
1555
1571
  return SHACLFlow.fromLinks(flowLinks, flowUri);
1556
1572
  }
1557
1573