Ad4mModel Refactor

[jhweir]

Ad4mModel Refactor — SHACL-native ORM, full test suite refactored

Summary

This PR completes the full Ad4mModel refactor started in the feat/shacl-sdna-migration base. The legacy Prolog-based subject class system is removed from the TypeScript ORM layer. Ad4mModel is now a clean, SHACL-native ORM backed entirely by SurrealDB, with a Prisma-inspired query/decorator API, atomic transactions, reactive subscriptions, and eager-loading via IncludeMap. The monolithic 3,917-line Ad4mModel.ts has been decomposed into focused modules and is now 759 lines. The full ad4m test suite has been refactored.

---

What changed

⚠️ Breaking changes

• baseExpression → id on all Ad4mModel instances — get baseExpression() public getter removed; PerspectiveProxy and Rust keep baseExpression at the protocol level
• writable → readOnly on PropertyOptions / SHACLPropertyShape (inverted semantics: readOnly: true means no setter)
• collection* → relation* — setCollection* methods renamed to set*; CollectionSetter Rust enum variant renamed to RelationSetter
• update() instance method removed — use save() for instance updates or the new static Ad4mModel.update()
• run() alias removed on ModelQueryBuilder — use .get()
• InstanceQuery decorator removed — use findAll() / ModelQueryBuilder
• generateSDNA() removed from @ModelOptions
• useSurrealDB flag and useSurrealDB() method removed from ModelQueryBuilder
• isInstance, prologCondition, where.condition removed from the query API
• Query.source and ModelQueryBuilder.source() removed — has_child source-scoping is gone
• useLiveQuery(Model, perspective, options?) — perspective is now arg 2, not inside options; useModel removed from both react and vue hooks
• ParentScope is now a union: { model, id, field? } or { id, predicate } (raw form)

---

� Migration guide

1. baseExpression → id

// Before:
const post = await Post.findOne(perspective, { where: { title: "Hello" } });
console.log(post.baseExpression); // "ad4m://abc123"

// After:
console.log(post.id); // "ad4m://abc123"

2. Decorator names and options

// Before:
@ModelOptions({ name: "Post" })
class Post extends Ad4mModel {
  @Optional({
    through: "flux://has_title",
    resolveLanguage: "literal",
    writable: true,
  })
  title: string;

  @Property({
    through: "flux://has_body",
    resolveLanguage: "literal",
    writable: true,
  })
  body: string;

  @ReadOnly({ through: "flux://has_slug", resolveLanguage: "literal" })
  slug: string;

  @Collection({ through: "flux://has_child" })
  comments: string[];
}

// After:
@Model({ name: "Post" })
class Post extends Ad4mModel {
  @Property({ through: "flux://has_title" })
  title: string;

  @Property({ through: "flux://has_body", required: true })
  body: string;

  @Property({ through: "flux://has_slug", readOnly: true })
  slug: string;

  @HasMany(() => Comment, { through: "test://has_comment" })
  comments: Comment[] = [];
}

3. Static create / update / delete

// Before — manual three-step pattern:
const post = new Post();
post.title = "Hello";
await post.save(perspective);

const existing = new Post();
existing.id = "ad4m://abc123";
await existing.getData(perspective);
existing.title = "Updated";
await existing.save(perspective);

const toDelete = new Post();
toDelete.id = "ad4m://abc123";
await toDelete.deleteSubject(perspective);

// After — single-call static API:
const post = await Post.create(perspective, { title: "Hello" });

await Post.update(perspective, "ad4m://abc123", { title: "Updated" });

await Post.delete(perspective, "ad4m://abc123");

4. Transaction API

// Before (fragile — leaked batch if any save threw):
const batchId = await perspective.createBatch();
await a.save(batchId);
await b.save(batchId);
await perspective.commitBatch(batchId);

// After:
await Ad4mModel.transaction(perspective, async (tx) => {
  await a.save(tx.batchId);
  await b.save(tx.batchId);
});

5. useLiveQuery / useModel (ad4m-hooks)

// Before — useModel, perspective inside options:
const { entries: posts } = useModel(Post, {
  perspective,
  where: { published: true },
});

// After — useLiveQuery, perspective is arg 2:
const { data: posts } = useLiveQuery(Post, perspective, {
  where: { published: true },
});

6. Query builder — run() → get(), subscribe() → live()

// Before:
const results = await Post.query(perspective).where({ published: true }).run();
Post.query(perspective).subscribe((posts) => console.log(posts));

// After:
const results = await Post.query(perspective).where({ published: true }).get();
Post.query(perspective).live((posts) => console.log(posts));

7. ModelQueryBuilder.source() / Query.source removed

// Before — source-scoping via has_child:
Post.query(perspective).source(parentId).get();

// After — use parent option:
Post.query(perspective)
  .parent({ model: Parent, id: parentId, field: "posts" })
  .get();
// or equivalently via findAll:
Post.findAll(perspective, {
  parent: { model: Parent, id: parentId, field: "posts" },
});

---

�🗑️ Prolog removal & SHACL/SurrealDB migration

TypeScript — Prolog query paths removed:

• Deleted Subject.ts — necessary bits inlined into PerspectiveProxy as a local class
• Deleted queryToProlog(), instancesFromPrologResult(), countQueryToProlog(), and all build*Query helpers
• Deleted @InstanceQuery decorator and InstanceQueryParams interface
• Deleted generateSDNA() from @ModelOptions
• Removed prologGetter / prologSetter from PropertyOptions, PropertyMetadata, Optional(), Property(), ReadOnly() interfaces
• Removed useSurrealDB flag and useSurrealDB() method from ModelQueryBuilder
• Renamed makeRandomPrologAtom → makeRandomId

Rust — Prolog→SHACL generation removed:

• Removed parse_prolog_sdna_to_shacl_links (328-line function) and backward-compat Prolog→SHACL code generation from add_sdna; SHACL→Prolog direction (shacl_to_prolog.rs) kept for compatibility
• Extracted shacl_to_prolog.rs — SHACL→Prolog compat code moved into its own module with comprehensive unit tests
• Fixed sdnaCode nullable in GraphQL schema — was String!, must be String since Prolog is now optional

SHACL/SurrealDB migration:

• Migrated all flow methods to SHACL — rewrote sdnaFlows, availableFlows, startFlow, expressionsInFlowState, flowState, flowActions, runFlowAction in PerspectiveProxy.ts to use SHACLFlow/getFlow() instead of Prolog infer() calls
• Removed subjectClassesFromSHACL GraphQL endpoint — replaced with client-side SHACL link queries via findClassByProperties()
• Replaced buildQueryFromTemplate() / Prolog-based SubjectClassOption with client-side SHACL matching via findClassByProperties(); then replaced by a single SurrealDB query (two-pass client-side processing) to avoid N+1 round trips; subjectClassesByTemplate falls back to findClassByProperties() when class name lookup fails
• Used SHACLShape.toJSON() in ensureSDNASubjectClass instead of manual JSON; getSubjectClassMetadataFromSDNA now uses getShacl()/SHACLShape.fromLinks()
• Batched SHACL/Flow link writes — addShacl()/addFlow() use addLinks() batch API; getShacl()/getFlow() use a single querySurrealDB() call instead of individual get() calls
• Converted ends_with filters to SurrealDB string::ends_with queries (5 functions in perspective_instance.rs that previously fetched all and filtered in memory)
• Fixed SurrealQL function name: string::starts_with not starts::with; replaced SQL LIKE with string::starts_with in getFlow()
• Executor commit ordering fix — update_prolog_engines() (which spawns the pubsub link-added task) previously ran before persist_link_diff() (the SurrealDB write); any subscriber calling findAll() immediately on link-added would read stale data; order swapped so SurrealDB is committed before pubsub fires

---

�️ Ad4mModel decomposition

Ad4mModel.ts went from 3,917 → 759 lines across the following extractions:

File	Contents
model/types.ts	WhereCondition, Query, IncludeMap, ModelMetadata, subscription types
model/schema/metadata.ts	getModelMetadata(), assignValuesToInstance(), ModelValueTuple
model/schema/fromJSONSchema.ts	createModelFromJSONSchema, determinePredicate, determineNamespace
model/query/surrealCompiler.ts	Pure SurrealQL builder helpers
model/query/operations.ts	queryToSurrealQL, instancesFromSurrealResult, findAll, findOne, findAllAndCount, paginate, count
model/query/hydration.ts	hydrateInstanceFromLinks(), evaluateCustomGetters() — shared between single-instance and bulk paths
model/query/fetchInstance.ts	6-stage single-instance hydration pipeline (getData() body)
model/query/snapshot.ts	Snapshot-based dirty tracking
model/query/ModelQueryBuilder.ts	Fluent query builder class
model/mutation.ts	MutationContext, setProperty, setRelation*, saveInstance, innerUpdate, cleanCopy
model/transaction.ts	runTransaction, TransactionContext
model/subscription.ts	createSubscription(), shared registry, fingerprinting
model/parentUtils.ts	normalizeParentQuery(), resolveParentPredicate()

Unified hydration — getData() (single-instance) and instancesFromSurrealResult() (bulk) previously had divergent hydration implementations (one using latest-wins, the other first-wins); both now share hydrateInstanceFromLinks() from hydration.ts with consistent latest-wins ordering.

Transaction API:

// Before (fragile — leaked batch if any save threw):
const batchId = await perspective.createBatch();
await a.save(batchId);
await b.save(batchId);
await perspective.commitBatch(batchId);

// After:
await Ad4mModel.transaction(perspective, async (tx) => {
  await a.save(tx.batchId);
  await b.save(tx.batchId);
});

Include API / IncludeMap:

// Prisma-style eager loading — relations stay as bare IDs unless include is set
Recipe.findAll(perspective, {
  include: {
    comments: true,
    tags: { where: { active: true }, limit: 5 },
  },
});

Removed the old relations field and .relations() fluent method. Nested include maps are supported: setting a relation key to another IncludeMap object (rather than true) recursively hydrates that relation's own relations.

---

🎨 Decorator & relation API

• Introduced @Model, @HasMany, @HasOne, @BelongsToOne, @BelongsToMany decorators
• WeakMap metadata registry keyed on constructor (not prototype) — eliminates a silent inheritance/data-corruption bug for subclassed models
• @BelongsToOne / @BelongsToMany decorators with direction='reverse'/maxCount; HasMany/HasOne accept an optional model factory argument
• Renamed setCollection* → set* throughout the public API; PerspectiveProxy.isCollectionSetter() now uses metadata instead of a string prefix check
• @HasOne hydration fix — getData() and instancesFromSurrealResult() now apply a maxCount === 1 guard so @HasOne fields resolve to a scalar string, not an array
• @Flag SHACL wiring — generatePropertySetterAction() throws if metadata.flag is set; innerUpdate() skips flag fields; flags are immutable after creation; @Flag now automatically sets readOnly: true
• Renamed writable → readOnly throughout the stack (inverted semantics): PropertyOptions.writable → readOnly, SHACLPropertyShape.writable → readOnly in toTurtle/toLinks/fromLinks/toJSON/fromJSON, Rust PropertyShape.writable → read_only with #[serde(rename = "readOnly")], PerspectiveProxy.writablePredicates → readOnlyPredicates with inverted guard logic for isSubjectInstance matching
• @Property auto-derive initial — generateSHACL() now auto-derives effectiveInitial = "literal://string:" for any writable non-flag property without an explicit initial; destructor actions always added for all writable non-flag properties; users only need initial: for semantic defaults (e.g. "todo://ready")
• resolveLanguage: "literal" is now the implicit default — decorators.ts auto-injects it into the SHACL shape for all non-flag properties so the Rust executor always uses fn::parse_literal; all explicit resolveLanguage: "literal" annotations removed from decorators and fromJSONSchema calls
• Model inheritance via SHACL sh:node — SHACLShape gains parentShapes, addParentShape(), and emits sh:node in both toTurtle() and toLinks() serializers; child shape uses only own properties/relations and references the parent via sh:node instead of duplicating; runtime inheritance already worked via the WeakMap prototype-chain walk in getPropertiesMetadata/getRelationsMetadata
• Relation decorator validation — @HasMany, @HasOne, @BelongsToMany, and @BelongsToOne throw a clear error at class-definition time if the through predicate is missing, instead of silently producing broken SHACL shapes
• RelationSetter backwards-compat alias — Rust CollectionSetter enum variant gains a #[serde(alias = "collectionSetter")] so existing serialised data written with the old name continues to deserialise correctly
• Updated @we/models and the test app to the new decorator names

---

🚀 Query & mutation API

Static convenience methods:

• Ad4mModel.create<T>(perspective, data, options?) — static factory that constructs, assigns, and saves in one call; options.parent links the new instance to a parent node atomically (predicate auto-inferred from @HasMany relations when field is omitted); options.batchId batches both the save() and the parent link write in the same transaction
• Ad4mModel.update<T>(perspective, id, data, batchId?) — fetches the existing instance, merges the partial data, then saves; replaces the common three-step new/assign/save pattern
• Ad4mModel.delete(perspective, id, batchId?) — constructs an instance by id, automatically removes all incoming links ({ target: id }) so parent collection queries stay consistent, then calls removeSubject(); replaces the new/delete two-step
• Ad4mModel.register(perspective) — thin wrapper around ensureSDNASubjectClass() for a consistent static API

Query extensions:

• Query.linkedFrom: { id, predicate } — parent-scoped graph-traversal filter; compiles to count(<-link[WHERE predicate='...' AND in.uri='...']) > 0 in SurrealQL; subscription layer watches linkedFrom.predicate so child additions/removals trigger live re-queries
• Query.parent — higher-level alternative to linkedFrom accepting ParentQueryByPredicate | ParentQueryByModel; normalizeParentQuery() resolves the model-backed form to { id, predicate } by scanning @HasMany metadata; wired through surrealCompiler, operations.ts, subscription.ts, and ModelQueryBuilder
• Where-filtering on relation fields — buildGraphTraversalWhereClause() now handles relation names in the where clause (was silently skipped); forward relations compile to ->link[WHERE predicate AND out.uri = value] > 0; reverse relations compile to <-link[WHERE predicate AND in.uri = value] > 0; IN, not, and not-IN variants all supported
• Nested include support — operations.ts now follows Query.include maps recursively (was hard-coded to false for sub-queries); multi-level depth guard prevents infinite recursion
• Include sub-query order preservation — fixed include sub-query result ordering when the sub-entry has its own order clause
• Remove has_child and source-scoping — Query.source, ModelQueryBuilder.source(), and has_child link write on create path removed; legacy perspectives had meaningless source → ad4m://has_child → baseExpression links

Internal fixes:

• Snapshot-based dirty tracking (model/query/snapshot.ts) — captures a deep snapshot of all field values after hydration; innerUpdate() checks isDirty() before re-writing each property/relation, preventing duplicate link writes for unchanged relations (fixes channel-pinning duplication); snapshot captured in both fetchInstance.ts and operations.ts after hydration
• Properties projection fix — cleanCopy() now only deletes schema-declared fields, preserving internal ORM machinery (_id, _perspective, generated addX/removeX/setX methods)
• TypeScript private instead of JS # fields — JS hard-private # fields use WeakMap semantics that fail when this is a Vue reactive Proxy; switched to TypeScript private (_) so Ad4mModel instances can be stored directly in Vue reactive state without toRaw() wrappers
• Fix stableFingerprint — was always undefined because it referenced the deleted baseExpression field; now uses id; instanceToSerializable() helper extracted for DRYness and circular JSON safety
• Fix multi-field sort dropping all but the first key in operations.ts
• Fix count() N+1 — added hasJsFilterConditions() fast path; count() was hydrating all rows just to count them
• Fix queryToSurrealQL SELECT — was ->link AS links (returns only id/uri); fixed with a correlated subquery returning predicate, out.uri as target, author, timestamp; removed phantom $perspective filter (silent no-op)
• matchesCondition fix for combined operators — not and between folded into the allMet chain in surrealCompiler.ts so they compose correctly with other WhereCondition operators
• normalizeTimestamp for numeric min/max — hydrateInstanceFromLinks now normalises timestamps before numeric min/max comparison, fixing latest-wins ordering for links with sub-second timestamps
• resolveLanguage implicit default in compiler — surrealCompiler.ts uses fn::parse_literal for both undefined and "literal" in WHERE comparisons

---

🔄 Subscription system

Client-side link-listener subscription (replaces server-push SurrealDB subscriptions):

• New createSubscription<T>() in subscription.ts — fires immediately then on every relevant link-added/link-removed
• Relevance check: only re-queries when a changed link's predicate belongs to the model (properties + relations); watches linkedFrom.predicate for parent-scoped queries
• Shared registry: identical (model, query) pairs on the same perspective share one findAll() execution and one set of link listeners via a WeakMap-keyed registry
• Result fingerprinting (stableFingerprint): callbacks only fire when the result set actually changed; includes @HasMany/@HasOne relation fields so relation-only mutations (e.g. addTags) trigger re-broadcast
• Late subscriber fast-path: second subscriber receives cached lastResults immediately via microtask
• Last-subscriber teardown: shared entry and listeners are fully cleaned up when listener count reaches zero
• 50 ms coalesce window (SETTLE_MS) to batch rapid link events from a single save() into one re-query
• .live(callback) fluent terminal on ModelQueryBuilder alongside .get()

Server-push SurrealDB subscription removal:

Deleted the legacy server-side SurrealDB subscription system made redundant by the above:

TypeScript (client):

• Removed isSurrealDB field from QuerySubscriptionProxy and its if/else surreal branches in subscribe(), keepalive loop, and dispose()
• Deleted subscribeSurrealDB() from PerspectiveProxy
• Deleted perspectiveSubscribeSurrealQuery(), perspectiveKeepAliveSurrealQuery(), perspectiveDisposeSurrealQuerySubscription() from PerspectiveClient

Rust (server):

• Deleted SurrealSubscribedQuery struct
• Dropped trigger_surreal_subscription_check and surreal_subscribed_queries fields + Arc::new() initialisers from PerspectiveInstance
• Removed surreal_subscription_cleanup_loop() from start_background_tasks()
• Deleted 5 functions: subscribe_and_query_surreal, keepalive_surreal_query, dispose_surreal_query_subscription, surreal_subscription_cleanup_loop, check_surreal_subscribed_queries
• Deleted 3 GraphQL mutation resolvers: perspective_subscribe_surreal_query, perspective_keep_alive_surreal_query, perspective_dispose_surreal_query_subscription
• Removed two trigger_surreal_subscription_check trigger lines from the link-added/link-removed update paths

Net: –876 lines, +769 lines across 4 files.

---

🪝 ad4m-hooks — useLiveQuery API

• Deleted helpers/src/ entirely — SubjectRepository, SubjectFactory, cache.ts, getProfile.ts and their index re-exports removed; ad4m-hooks/helpers package removed from pnpm workspace, package.json, and publish workflows
• Deleted from both react and vue — useMe, usePerspectives, useAgent, usePerspective, register — app-level concerns already implemented in consumer repos
• Replaced useModel with useLiveQuery in both react and vue packages:
  • useLiveQuery(Model, perspective, options?) — perspective is now arg 2, not inside options
  • Parent scope — parent: ParentScope restricts results to children of a parent node; ParentScope is { model, id, field? } (auto-resolves predicate) or { id, predicate } (raw form); bails out early when parent.id is falsy to handle web-component property-assignment races
  • Single-instance mode — id option returns LiveInstanceResult<T> instead of a list
  • Load-more / infinite-scroll pagination via loadMore() / pageSize option
  • preserveReferences mode for stable object identity across re-renders
  • String model name override for generic class browsers
  • isRef() normalisation of the perspective prop in Vue hook so both raw values and refs are accepted
  • Active subscription torn down on perspective / query / page change and on onUnmounted/cleanup
  • Entries keyed on entry.id (was entry.baseExpression)
• Net: –1,292 lines, +144 lines initial slim; further +649/–285 lines for useLiveQuery rewrite (21 files)

---

🔧 Executor — JS bundle Deno ESM compatibility

• executor/esbuild.ts post-build buffer patch — safe-buffer@5.2.1 (inside @transmute/did-key-ed25519) was bundled as a __commonJS wrapper that emitted var buffer2 = __require("buffer"). Deno's ESM runtime cannot execute require() calls, so coreInit() threw Dynamic require of "buffer" is not supported, the executor started its HTTP server but silently failed all GraphQL operations, and integration tests hung until timeout. Fixed by adding a post-build regex replacement in esbuild.ts that rewrites all __require("buffer"|"node:buffer") calls to reference the existing top-level import buffer from "node:buffer" already present in the bundle.
• Added // @ts-nocheck to executor/esbuild.ts — tsc never processes this Deno script; suppresses ~35 pre-existing URL-import and implicit-any errors.
• rust-executor agent data directory — init_global_instance() now creates {app_path}/ad4m/ before constructing AgentService; the nested subdirectory was never created so std::fs::write() panicked with Failed to write agent file: Os { code: 2, kind: NotFound } on fresh CI workdirs.

---

⚙️ CI

• Replaced Docker executor (coasys/ad4m-ci-linux) with self-hosted machine runner coasys/marvin (AMD Ryzen 9 9950X, 60 GB RAM, Ubuntu 25.04; Rust 1.92, Node 18, Deno, Go, pnpm pre-installed)
• Removed remote cache — restore/save_cache was uploading/downloading the full Rust target/ dir (~20 GB) causing 29-minute cache restore steps on every run; the persistent machine runner does incremental compilation instead (cleanup_working_directory: false)
• Fixed nvm stdout corruption in cargo build scripts — nvm use 18 in $BASH_ENV printed Now using node v18.20.8 to stdout which corrupted the libffi link step via a bash syntax error in a subshell; fixed by adding the Node 18 bin dir directly to PATH
• Isolated setup port ranges per concurrent job — ports.ts now assigns non-overlapping port windows per CI job index so parallel integration-tests-core and integration-tests-multi-user jobs don't collide on port 12000; added waitForPortFree() pre-check
• Added prepare-test step to integration-tests-js and integration-tests-multi-user jobs — ensures the executor binary and bootstrap seed are freshly prepared before each suite; bootstrap seed reset cleanly before each prepare-test invocation
• Renamed CircleCI jobs for clarity: build-and-test → build, integration-tests-js → integration-tests-core, integration-tests-multi-user-simple → integration-tests-multi-user; removed duplicate integration-tests-email-verification (covered by test-auth inside test:ci); bumped multi-user job timeout to 60 min

---

🧪 Test suite

Infrastructure:

• Added helpers/ directory: ports.ts (dynamic port allocation), executor.ts (AgentHandle), assertions.ts (waitUntil), index.ts (barrel)
• Added wipePerspective() export to utils/utils.ts
• Centralized global.fetch polyfill into tests/setup.ts
• Migrated auth and multi-user tests to a shared startAgent helper
• Removed findAndKillProcess entirely — matched any process by name and could kill a live AD4M instance; teardown already uses tree-kill with the specific child PID

New model test suite (tests/model/):

• models.ts — TestPost, TestComment, TestTag, TestBaseModel, TestDerivedModel, TestChannel, TestReaction fixture models
• model-core.test.ts — 20 CRUD + decorator coverage tests; Ad4mModel.update() and .delete() integration tests
• model-query.test.ts — 16 sections covering where/order/limit/offset/count/paginate/findAllAndCount/include/parent queries/dirty tracking (~1,100 lines)
• model-subscriptions.test.ts — live subscription tests using .live() API; parent-scoped subscription tests; @HasMany re-fire regression test
• model-transactions.test.ts — batch/transaction pattern tests including rollback (7 tests) + 3 dirty-tracking tests
• model-inheritance.test.ts — metadata isolation, SHACL, polymorphic findAll tests
• model-where-operators.test.ts — 9 tests covering all WhereCondition operators (IN, not, contains, gt, gte, lt, lte, between)
• model-prolog.test.ts — 5 pure-function tests for generatePrologFacts() + 2 executor infer() tests
• Unit tests for normalizeParentQuery() and queryToSurrealQL() with parent and linkedFrom options in Ad4mModel.test.ts

Reorganisation:

• Split monolithic multi-user-simple.test.ts into 8 focused test files
• Reorganised tests into subfolders (auth/, model/, sdna/, multi-user/)
• Renamed prolog-and-literals.test.ts → sdna.test.ts; removed duplicate model tests from it
• Script renames across the monorepo: test-main → test, test-all → test-run, test-run → test:ci; removed legacy aliases; combined auth scripts; folded test-from-json-schema into test-model

Test runner fixes:

• Replaced stale findAndKillProcess('holochain') / findAndKillProcess('lair-keystore') with findAndKillProcess('ad4m') — everything is a single ad4m-executor process since the Rust refactor
• Switched from downloading stale pre-built language bundles (CJS, required ESM conversion) to the bootstrap seed (tests/js/bootstrapSeed.json); removed node-wget-js and unzipper dependencies
• Shell EXIT trap added to the Mocha run script — guarantees executor cleanup after the last suite finishes or on unexpected failure
• AgentHandle.stop() now clears and unrefs the fallback SIGKILL timer after a clean exit so Node doesn't linger
• injectPublishingAgent.js retries with exponential backoff — prevents flaky failures when the executor is slow to become ready
• @BelongsToMany CI stabilisation — wrapped findOne call in waitUntil (5 s timeout, 100 ms poll) to eliminate a read-cache race on slower CI machines
• Triple-agent DHT gossip lag fix (triple-agent-test.suite.ts) — expected 16 to equal 20 flake caused by Holochain HolochainRetreiver: Could not find entry errors; fixed by calling makeAllThreeNodesKnown() mid-test before Jim's poll, adding a 10 s pre-sleep, increasing per-retry interval 1 s → 3 s, increasing retry count 20 → 40, bumping suite this.timeout 200 s → 420 s
• Lazy-load PUBLISHING_AGENT in runtime.suite.ts — prevents startup-ordering crash when the agent is not yet initialised at module load time
• Added process-level unhandledRejection guard that silently swallows WebSocket 1006 close errors escaping observable chains before per-client guards fire

Key fixes found during test rebuild:

• register() calls added to beforeEach in all model test files — SHACL definitions are stored as links and don't survive wipePerspective()
• Transaction tests rewritten to avoid create+delete within the same batch (the runtime doesn't handle constructor+destructor for the same entity in one committed batch)
• Fixed same-batch double-save bug: _savedOnce flag passes an alreadyExists hint to saveInstance() to skip the SurrealDB existence-check on subsequent saves in the same uncommitted batch
• Fixed @BelongsToMany include hydration

---

🐛 Bug fixes

ORM layer:

• Fixed save() create/update routing: checks SurrealDB for existing links before branching; setProperty() now encodes raw values as literal:// URIs before passing to executeAction, mirroring Rust's resolve_property_value
• Fixed innerUpdate emitting Property X has no metadata, skipping noise for generated relation methods and un-decorated fields; setProperty now throws for truly unknown direct calls
• Fixed quote escape no-op in fetchInstance.ts (.replace(/'/g, "'") replaced with same character)
• Circular JSON fix in createSubject — JSON.stringify call on the subject instance threw on circular references; fixed by using instanceToSerializable() which walks only declared field metadata
• Literal.get() strict boolean parsing — rejects payloads that are not exactly "true" or "false" instead of silently coercing via Boolean()
• Literal.toUrl() throw on unsupported type — throws a descriptive error instead of returning a malformed URL
• Literal-guard fix (from origin/dev merge) — hydration.ts (resolveValue()) already incorporates a strictly-superior guard (resolveLanguage === "literal" || resolveLanguage === undefined) covering both explicit literal properties and plain undecorated string fields

Networking / multi-user:

• Fixed neighbourhood signal routing: send_signal() and send_broadcast() in perspective_instance.rs only searched list_user_emails() to decide if a recipient is local; the main agent has no email so signals to it fell through to the link language; fixed to also check the main agent's DID
• Fixed broadcast loopback — broadcasts skip local delivery when owners is None or empty; owners=None/[] treated as implicit main-agent ownership for legacy perspectives
• Neighbourhood Apollo signal subscription disposal — NeighbourhoodClient stores the ZenObservable subscription in a #signalSubscriptions map; removeSignalHandler() calls .unsubscribe() and fully cleans up both maps when the last handler for a perspective is removed, preventing a leaked WebSocket stream
• WebSocket 1006 isSocketCloseError guard — added isSocketCloseError(e) to core/src/utils.ts; applied across all six Apollo/graphql-ws subscription clients (PerspectiveClient, AgentClient, RuntimeClient, AIClient, NeighbourhoodClient, NeighbourhoodProxy — 16 handlers total); errors silently swallowed only for the expected shutdown case
• Fixed infer() call in perspective_instance.rs not awaiting findAndKillProcess in error handlers
• Multi-user test suite fixes: auth flow, error strings, URI validation, bootstrap timing

---

📄 Documentation

• Added AD4M-MODEL-REFACTOR.md refactor plan (continuously updated through 2026-02-24); backlog items for future PRs consolidated into core/src/model/IMPROVEMENTS.md
• Added core/src/model/README.md — architecture overview, full Recipe example, decorator reference table, query API cheatsheet, transaction pattern, fromJSONSchema examples, inheritance notes; corrected two method name errors after initial authoring (.run() → .get(), .subscribe() → .live() on the fluent builder)
• Added Phase G deprecation plan — documents what can be removed from PerspectiveProxy / Rust once Flux and ad4m-hooks migrate off the Subject proxy API to Ad4mModel (getSubjectData, getSubjectProxy, Rust get_subject_data())
• Added SUBSCRIPTION_STRATEGY.md — documents client-side subscription architecture, multi-user node compatibility, shared registry design
• Trimmed JSDoc verbosity by 24–37% across Ad4mModel.ts, decorators.ts, transaction.ts, types.ts
• Updated CHANGELOG with 21 unreleased entries since 0.11.1 (Fixed ×11, Added ×5, Changed ×5)