Let's get all the clients on par with the latest changes in the base .NET/C# client in the Chronicle repository. Get ...

[cratis-direct]

Let's get all the clients on par with the latest changes in the base .NET/C# client in the Chronicle repository. Get the Kotlin, TypeScript and Elixir up to the latest feature set. Fix documentation and code snippets so that we can see the samples for these clients as well.

Scheduled as ad-hoc work; a pull request referencing this issue may follow.

---

Posted by Stagehand (AI) - an autonomous agent, not a person. Review accordingly.

[einari]

Plan — TypeScript client parity with the .NET gold standard

Scoped against Chronicle/Source/Clients/DotNET. Two tracks: a correctness track (things
that are silently wrong today) and a coverage track (things that are simply absent).

Track 1 — compliance correctness (do this first)

1a. Class-level @pii() does not mark the class's own properties.

C# Compliance/GDPR/PIIMetadataProvider.cs:28-32 treats a property as PII when the property,
its declaring type, its property type, or its constructor parameter carries [PII].
Source/schemas/JsonSchemaGenerator.ts:159-183 implements only the first and third:

// property-level
if (ComplianceMetadataResolver.hasMetadataFor(target, propertyKey)) { ... }
// type-level, on the PROPERTY's type (the concept case)
if (propertyType) { ComplianceMetadataResolver.getMetadataForType(propertyType) }

getMetadataForType is never called with the declaring class. So:

@pii()
@readModel()
class PersonProfile { name = ''; email = ''; }

emits a schema with no compliance entries at all, and every field is persisted in the
clear — where C# would encrypt all of them. This is a data-protection defect, not a doc gap.
Fix in addComplianceMetadata by also consulting the declaring class, and add specs covering
class-level, property-level, concept-typed, and the combination.

1b. Compliance metadata is not pushed down to schema leaves, and is not de-duplicated.
Port AddComplianceMetadata / HasMetadataOfType from
Chronicle/Source/Clients/DotNET/Schemas/JsonSchemaGenerator.cs:133-161. Without the descent, a
@pii() composite value object leaves the marker on the container node; the release walk then
hands back a string where the schema says object and the read model fails to materialize.

1c. Arrays of concept-typed PII lose their classification. C# has an explicit
enumerable branch carrying the element concept's compliance metadata onto the item schema.

1d. @subject() decorator + resolver. readModels/ReadModels.ts:348-355 and
MaterializedReadModels.ts:144-150 hardcode the id property as the compliance subject, and
ReadModels.ts throws when it is absent. C# uses [Subject] with SubjectResolver /
ReadModelSubjectResolver. The subject decides which encryption key is used — getting it wrong
means undecryptable data.

1e. Smaller compliance gaps: no PIINotSupportedOnEventSourceId guard, no
[ComplianceDetails] equivalent, IPIIManager missing allowNewEncryptionKeyFor, and
compliance is written through a Record<string, unknown> cast because it is not declared on
the JsonSchema type.

Track 2 — documentation coverage

Of 759 shared snippet IDs, TypeScript resolves 256 to a real snippet (33.7%), 23 to a
"TypeScript does not support this workflow yet." fence, and 480 to nothing at all. That is
the best of the four clients and still leaves two-thirds of the shared corpus blank on the
TypeScript tab.

Re-check the 23 existing fences against the source in the same pass — the Kotlin client has 107
fences under projections/** for capabilities that demonstrably exist, and a stale "not
supported" is a worse defect than a blank tab. TypeScript's count is small enough that this is
cheap insurance.

Missing per area:

projections 76   configuration 22   migrations 11   subscriptions 10
code-analysis 66  contributing  15   namespaces  11   constraints    9
testing     53   compliance    16   get-started 16   scenarios      7
reducers    42   hosting       15   read-models 13   (remainder < 7)
events      26   reactors      26   concepts    25

For each missing ID: read the shared page that references it and the C# snippet as the
statement of intent, then write the idiomatic TypeScript equivalent — or, where the client
genuinely lacks the capability, the documented

TypeScript does not support this workflow yet.

fence. An honest "not yet" is a valid answer; a blank tab is not. Everything must pass
python3 Documentation/validate-client-snippets.py, which really compiles the snippets
(green at baseline today).

compliance/** goes first — it is the area this work started from, and 16 of its 25 IDs are
missing, including every pii-with-concepts entry beyond the three that exist.

Track 3 — absent feature areas, ranked

1. IProjections operational surface — projections/IProjections.ts has two methods
   (discover, register) against ~18 in C#. Missing getStateForModel, replay,
   getFailedPartitionsForModel, hasFor, query (PDL), getProjectionIdFor. Blocks all
   operational tooling.
2. Captures — no Source/captures directory at all; C# has 39 files across both the fluent
   ICaptureBuilder and the ModelBound/ attribute set. Largest wholly-absent feature.
3. Tags and event-tag filtering — @tag / @tags / @filterEventsByTag. The wire fields
   are already being sent as empty arrays (reactors/Reactors.ts:242,
   seeding/EventSeeding.ts:111), so this is plumbing an existing contract.
4. Registrations — RegistrationOutcome on IEventStore plus waitForRegistration,
   replacing the ad-hoc registerWithRetry() in projections/Projections.ts (5 attempts,
   string-matched gRPC codes).
5. Reactor [OnceOnly] / [Replay] / middleware — IsReplayable: false is hardcoded, so
   replay-safety semantics are unavailable.
6. Model-bound completeness — @fromAll, @noAutoMap (AutoMap.Enabled is hardcoded at
   Projections.ts:395), per-model eventSequence (always event-log), root-level
   @clearWith (currently only consumed inside childrenAndNestedBuilder.ts), and record
   constructor-parameter mapping.
7. Remainder — revise on IEventSequence, [Index] on read models, IReadModelReactors,
   Keys (@key / @contextKey), model-bound constraints (@unique, @removeConstraint),
   [CompensationFor], Patterns.

Conventions

Specs are Vitest (Source/vitest.config.ts, include: ['**/*.spec.ts']) in flat
*.spec.ts files colocated with their source — 23 today. Note this diverges from
.ai/rules/specs.typescript.md, which mandates Mocha + Sinon + Chai .should and a
for_*/when_*/given/ hierarchy; follow what the repo actually does and raise the rule-file
drift separately. yarn compile after each new file, yarn test before concluding, zero
warnings. Copyright header on every file, American English.

---

Plan posted by Claude (AI) acting as orchestrator. Implementation is being carried out by
sub-agents against branch parity/full-client-parity.

[einari]

Landed — #59

Real snippet coverage of the shared docs: 256 → 408 of 759 (33.7% → 53.8%).

The headline fix is a data-protection defect: a class-level @pii() produced a schema with no compliance entries, so a @pii()-adorned read model or event was written in the clear where the .NET client would encrypt it. Compliance metadata now also descends to schema leaves and de-duplicates, arrays of concepts keep their classification, and allowNewEncryptionKeyFor is available.

Note the PR is labeled major: @pii() on a property named eventSourceId now throws. TypeScript has no EventSourceId type to guard on, so the check is on the conventional property name — encrypting the event source id makes its own decryption key unfindable, which is unrecoverable.

What remains

Documentation — 285 IDs carry an honest "does not support this workflow yet" fence; 66 remain absent and are code-analysis/** (the Roslyn analyzer catalog), deliberately left C#-only.

Source-level gaps, ranked:

1. @subject() decorator and subject resolver. readModels/ReadModels.ts:348 and MaterializedReadModels.ts:144 hardcode the id property as the compliance subject and ReadModels.ts throws when it is absent. The subject selects the encryption key, so getting it wrong means undecryptable data. Deliberately left out of this PR as a larger change.
2. IProjections operational surface — two methods (discover, register) against ~18 in C#. No getStateForModel, replay, getFailedPartitionsForModel, hasFor, or PDL query. Blocks all operational tooling.
3. Captures — no Source/captures directory at all; the single largest wholly-absent feature.
4. Tags and event-tag filtering — @tag/@tags/@filterEventsByTag. The wire fields are already sent as empty arrays, so this is plumbing an existing contract. Its absence accounts for roughly 30 of the remaining fences on its own.
5. No testing library — no EventScenario/ReadModelScenario equivalent, which is why all 53 testing/** IDs are fenced.
6. Registrations — RegistrationOutcome plus waitForRegistration, replacing the ad-hoc registerWithRetry() in Projections.ts.
7. Reactor [OnceOnly]/[Replay]/middleware — IsReplayable: false is hardcoded, so replay-safety semantics are unavailable.
8. Model-bound completeness — @fromAll, @noAutoMap (AutoMap.Enabled hardcoded), per-model eventSequence, root-level @clearWith, record constructor-parameter mapping.
9. revise, [Index], IReadModelReactors, Keys, model-bound constraints, [CompensationFor], Patterns.
10. No mTLS client certificates (certificatePath/certificatePassword parse but are never wired into createCredentials()), and no dynamic namespace resolver.

Unrelated pre-existing failure

fundamentalsPeerRange.spec.ts fails on main untouched: the peer range is ^7.14.0 while the pinned dev dependency is 7.18.2, and the spec asserts they match. Not touched here — package.json changes need explicit sign-off.