@lmzhen/dsh-evolution-core 0.26.15 → 0.27.0

package/lib/types/index.js

@@ -0,0 +1,101 @@
+/**
+ * Shared library for the dsh-evolution plugin family.
+ *
+ * Pure stores, prompts, signals, lifecycle logic, threat scanning, IO seam
+ * types, and session-event augmentations. This package ships no runtime
+ * plugin and no `./invariant` companion (v37 S2.1); consumers import named
+ * exports from the package root so published npm bundles never depend on
+ * source subpaths.
+ *
+ * ## Layer map (OPT-28, 2026-09) — locate code by LAYER, not by directory
+ *
+ * This one physical package carries THREE architecture layers of the family;
+ * when adding or looking for something, go by the export's layer:
+ *
+ * - **Cross-cutting basics** — `state-store.ts` (env roots — the single
+ *   source of DSH-home semantics), `serial.ts`, `numeric.ts`, `constants.ts`,
+ *   `mutations.ts`, `events.ts`, `gates.ts`, `errors.ts` (the error-code table),
+ *   `payload.ts` (which of `facts`/`content` is the payload — one rule for the whole family).
+ * - **Security primitives** — `threats.ts` (content threat scanner),
+ *   `redact.ts` (credential masking at model boundaries),
+ *   `fold-untrusted.ts` (untrusted text must not become prompt structure). Consumers:
+ *   evolution-policy/threat, both stores, review, maintenance.
+ * - **Core domain stores/logic** — `skill-store.ts` (skill tree engine +
+ *   IO-seam consumer), `memory-store.ts`, `usage.ts`, `curator.ts`,
+ *   `quality.ts`, `signals.ts`, `skill-reads.ts` (the read-before-write rule, shared by the
+ *   tool path and the review's plan path), `drift-signals.ts`, `skill-health.ts`,
+ *   `composition/composer.ts`, `prompts.ts`, `learn-prompt.ts`,
+ *   `evolution-events.ts`, `evidence.ts` (which session frames count as content, for the plan
+ *   path's evidence-class report), `session-projection.ts` (the live per-session units the family's
+ *   log-shaped readers read instead of re-reading the session log), `io.ts` (the ctx.evolutionIo
+ *   seam itself).
+ * @module @lmzhen/dsh-evolution-core
+ */
+export * from "./citations.js";
+// G1/1.1: the ONE authority behind a write (its type and the authorityFrom builder).
+export * from "./tree-write.js";
+export * from "./package-identity.js";
+export * from "./write-authority.js";
+export * from "./write-gates.js";
+export * from "./reference-rewrite.js";
+export * from "./cost.js";
+export * from "./skill-lint.js";
+export * from "./health-baseline.js";
+export * from "./curator.js";
+export * from "./evolution-events.js";
+export * from "./fuzzy-match.js";
+export * from "./gates.js";
+export * from "./guards.js";
+export * from "./http-routes.js";
+export * from "./events.js";
+export * from "./env.js";
+export * from "./errors.js";
+export * from "./io.js";
+export * from "./learn-prompt.js";
+export * from "./memory-store.js";
+export * from "./mutations.js";
+export * from "./prompts.js";
+export * from "./quality.js";
+export * from "./redact.js";
+export * from "./review-channel.js";
+export * from "./run-registry.js";
+export * from "./reports.js";
+export * from "./long-runs.js";
+export * from "./serial.js";
+export * from "./probe.js";
+export * from "./platform-services.js";
+export * from "./instance-scope.js";
+export * from "./write-inventory.js";
+export * from "./scope.js";
+export * from "./skill-health.js";
+export * from "./signals.js";
+export * from "./skill-reads.js";
+export * from "./skill-row-cells.js";
+export * from "./document-body.js";
+export * from "./evidence.js";
+export * from "./session-projection.js";
+export * from "./drift-signals.js";
+export * from "./skill-history.js";
+export * from "./unit-members.js";
+export * from "./skill-store.js";
+export * from "./store-ledger.js";
+export * from "./reachability.js";
+export * from "./state-store.js";
+export * from "./threats.js";
+export * from "./tool-dispatch.js";
+export * from "./usage.js";
+export * from "./constants.js";
+export * from "./params.js";
+export * from "./namespace-migration.js";
+export * from "./live.js";
+export * from "./numeric.js";
+export * from "./opt-in.js";
+export * from "./payload.js";
+export * from "./fold-untrusted.js";
+// G0 contract surface: /subagent types + state probe, /composition preset constants.
+export * from "./subagent/index.js";
+export { EVOLUTION_PRESET_IDS, REVIEWER_PRESET_ID, MAINTAINER_PRESET_ID, RESTRICTED_TOOLS_ROW_ID, RESTRICTOR_MODULE, RESTRICTED_PRESET_DISPLAY, } from "./composition/index.js";
+export * from "./diagnostics.js";
+export * from "./platform-line.generated.js";
+export * from "./session-fold.js";
+//# sourceMappingURL=index.js.map

package/lib/types/instance-scope.js

@@ -0,0 +1,69 @@
+/**
+ * B3 / G4 (0.3.78): the family's single-instance contract, made explicit.
+ *
+ * Every persisted sidecar is written under TWO assumptions: the IO backend's
+ * cross-process write lock serializes different processes, and exactly ONE
+ * instance of each writer service exists per evolution home. The second half
+ * was implicit — `makeSerialQueue()` and the module-scope stores are
+ * per-instance, so two rows writing one home interleave inside one file (the
+ * "two instances, one file" class). This module makes that half enforceable: a
+ * writer CLAIMS its key while mounted and releases it on dispose, and a second
+ * claimant is told who holds the key instead of silently racing it.
+ *
+ * The claim is keyed by the HOME, not by the process: the contended resource is
+ * the sidecar directory, so two instances resolving different homes (an
+ * isolated test fixture, a second DSH_HOME) do not contend, while two rows on
+ * one profile do.
+ *
+ * ## Scope (v43 FLOW2-1) — this registry is PER PROCESS
+ *
+ * `claims` below is a module-scope Map: two ROWS over one home in ONE process
+ * contend, while the SAME home in another process gets its own Map and is
+ * granted the key. That is by construction, not a gap to close here — the
+ * cross-process half of the contract is the IO backend's write lock
+ * (`transactIo`, core/io.ts), which serializes a per-target read-modify-write.
+ * The FLOW2-1 finding was three call sites reading a GRANTED claim as "no other
+ * process can be doing this work", so the caller contract is stated here:
+ * - granted means "no other row OF THIS PROCESS owns the key";
+ * - `instanceHolder()` answers "who holds it HERE"; `undefined` also covers
+ *   "held by another process";
+ * - a foreign holder's LIVENESS cannot be decided from a claim at all (no pid
+ *   is recorded here): a consumer that needs that decision must carry a pid in
+ *   its own credential and probe it (`isProcessAlive`, core/io.ts), or state
+ *   that its action is destructive.
+ * @module @lmzhen/dsh-evolution-core/src/instance-scope
+ */
+/** home+key -> holder, IN THIS PROCESS ONLY. The Map is module-scope, so two
+ * processes never share it: this half cannot exclude another process (v43
+ * FLOW2-1) — the cross-process half is the write lock, see
+ * persisted-write-inventory.json. It is still the whole point for the case it
+ * was written for: two ROWS of one process writing one home. */
+const claims = new Map();
+/** `<home> :: <key>` — the registry key, exported so diagnostics name the
+ * same unit the claim does. */
+export function instanceClaimKey(home, key) {
+    return `${home} :: ${key}`;
+}
+/** Take the claim for `key` at `home`. Grants while it is free or already
+ * held BY `owner` — remounting the same instance is not a second instance. */
+export function claimInstance(home, key, owner) {
+    const id = instanceClaimKey(home, key);
+    const current = claims.get(id);
+    if (current === undefined || current === owner) {
+        claims.set(id, owner);
+        return { granted: true, key: id, holder: owner };
+    }
+    return { granted: false, key: id, holder: current };
+}
+/** Release only the claim `owner` took — never another instance's. */
+export function releaseInstance(home, key, owner) {
+    const id = instanceClaimKey(home, key);
+    if (claims.get(id) === owner)
+        claims.delete(id);
+}
+/** The current holder of `key` at `home`, IN THIS PROCESS, or undefined
+ * (which also covers "another process holds it" — v43 FLOW2-1). */
+export function instanceHolder(home, key) {
+    return claims.get(instanceClaimKey(home, key));
+}
+//# sourceMappingURL=instance-scope.js.map