@t4r71/dsh-dual-axis 0.1.0

package/lib/session-store.js

@@ -0,0 +1,978 @@
+import z from "@deepseek-ai/schemastery";
+import "@deepseek-ai/dsh-sandbox";
+//#region lib/types/axis.js
+/**
+* The read/write ACCESS AXES of the file sandbox: the per-axis vocabulary a
+* session selects and the lossless mapping onto the legacy single `mode`.
+*
+* This is the 0.1.7 port of the algebra upstream deleted. 0.1.6 shipped it as
+* `@deepseek-ai/dsh-sandbox/access` (152 lines) and
+* `@deepseek-ai/dsh-sandbox/scope` (152 lines); 0.1.7 has neither symbol nor
+* file, so the package carries its own copy and keeps the 0.1.6 semantics
+* verbatim: four kinds, `custom` = base + allow - deny with deny winning.
+*
+* One axis answers "which absolute paths may this execution touch". `deny`
+* permits nothing, `workspace` permits the calling session's workspace root
+* plus the platform temp areas, `all` is the whole host filesystem, and
+* `custom` names a BASE kind plus absolute path ADDITIONS and REMOVALS —
+* path lists, not patterns.
+*
+* `mode` REMAINS the write axis's persistence spelling. The session-format
+* whitelist pins its literal values, so this module keeps `mode` derivable
+* from the write scope in both directions instead of replacing it:
+* {@link scopeOfMode} and {@link modeOfScope} are the two halves of that
+* bijection, and `custom` maps onto the mode implied by its own base.
+*
+* @module @t4r71/dsh-dual-axis/axis
+*/
+/** Every {@link AxisScopeKind}, for option advertisement and untrusted-value validation. */
+const AXIS_KINDS = [
+	"deny",
+	"workspace",
+	"all",
+	"custom"
+];
+/** Every {@link AxisBase}, for option advertisement and untrusted-value validation. */
+const AXIS_BASES = [
+	"deny",
+	"workspace",
+	"all"
+];
+/** The default READ axis: every mode permitted reading before the axes existed, so the whole host. */
+const DEFAULT_READ_SCOPE = { kind: "all" };
+/** The default WRITE axis: the session workspace plus the platform temp areas. */
+const DEFAULT_WRITE_SCOPE = { kind: "workspace" };
+//#endregion
+//#region lib/types/scope.js
+/**
+* Whether a configured path is spelled absolutely on this host. Both POSIX
+* (`/x`) and Windows (`C:\\x`, `\\\\server\\share`) spellings are accepted
+* because a policy may be authored for one world and resolved in another; the
+* canonical resolution that follows is what actually binds it to this host.
+* @param path - the configured path spelling.
+* @returns whether the spelling is absolute.
+*/
+function isAbsoluteSpelling(path) {
+	return path.startsWith("/") || /^[A-Za-z]:[\\/]/.test(path) || path.startsWith("\\\\");
+}
+//#endregion
+//#region lib/types/config.js
+/**
+* The dual-axis settings surface: the 0.1.7 spelling of the section 0.1.6
+* registered through `ctx.settings.installSection`.
+*
+* 0.1.7 removed both `installSection` and `settings.register(ns, schema)`:
+* `SettingsForms.describe()` projects exactly the Config schemas of LOADED
+* Loader entries (`packages/settings/settings/src/index.ts:302-340`) and
+* `write()` refuses a namespace with no matching entry
+* (`:382-384`, `No configurable plugin entry`). The namespace IS the entry
+* id, so this package's own row id in `cordis.patch.yml` — `dual-axis` — is
+* the settings namespace. 0.1.6's separate `sandbox-axis` namespace name is
+* therefore retired.
+*
+* 0.1.7 also added the volatile gate: a field that is not beneath a
+* `.volatile()` node is neither projected into the form
+* (`packages/settings/settings/src/schema.ts:37-47`) nor writable
+* (`:74-78`), and an entry with no volatile field at all is refused outright
+* (`index.ts:385-386`). Both axes are marked volatile here.
+*
+* The schema is deliberately `z.any()` per axis, exactly as in 0.1.6:
+* schemastery's union types strip the `custom` branch's `base/allow/deny`
+* payload, which would silently degrade a configured custom axis into an axis
+* carrying no paths. Shape validation is {@link normalizeScope}'s job.
+*
+* @module @t4r71/dsh-dual-axis/config
+*/
+/**
+* This package's row id in `cordis.patch.yml`. It doubles as the 0.1.7
+* settings namespace (the Loader entry id) and, prefixed with the package
+* name, as the `plugins.row.config` slot entry key the client half uses.
+*/
+const DUAL_AXIS_ROW_ID = "dual-axis";
+z.object({
+	read: z.any().volatile(),
+	write: z.any().volatile(),
+	groups: z.array(z.any()).default([]).volatile(),
+	defaultGroups: z.array(z.string()).default([]).volatile()
+});
+/**
+* Collect one `custom` axis's path list: every entry must be a non-empty
+* absolute path.
+* @param label - the axis name used in the error message.
+* @param entry - the list name used in the error message (`allow` or `deny`).
+* @param value - the untrusted list value.
+* @returns the validated path list.
+* @throws When the value is not a string array, or holds a non-absolute path.
+*/
+function pathList(label, entry, value) {
+	if (value === void 0) return [];
+	if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) throw new Error(`dual-axis: ${label} ${entry} must be an array of absolute path strings`);
+	for (const item of value) if (item.length === 0 || !isAbsoluteSpelling(item)) throw new Error(`dual-axis: ${label} ${entry} entry ${JSON.stringify(item)} must be an absolute path`);
+	return [...value];
+}
+/**
+* Coerce one axis value from a config document (which a human may have edited)
+* into a legal {@link AxisScope}, throwing rather than guessing.
+*
+* An unreadable axis must not become some other, wider or narrower grant:
+* throwing fails the row's mount or the settings write on the spot instead of
+* proceeding under an invented boundary. This is 0.1.6's `normalizeScope`,
+* unchanged.
+* @param label - the axis name used in error messages (`read` or `write`).
+* @param value - the untrusted axis value.
+* @returns the validated axis value.
+* @throws When the value is not one of the four kinds, or a custom entry is not absolute.
+*/
+function normalizeScope(label, value) {
+	if (typeof value !== "object" || value === null) throw new Error(`dual-axis: ${label} must be an access-axis object, received ${JSON.stringify(value)}`);
+	const candidate = value;
+	if (typeof candidate.kind !== "string" || !AXIS_KINDS.includes(candidate.kind)) throw new Error(`dual-axis: ${label} carries unknown kind ${JSON.stringify(candidate.kind)} (expected: ${AXIS_KINDS.join(", ")})`);
+	if (candidate.kind !== "custom") return { kind: candidate.kind };
+	if (typeof candidate.base !== "string" || !AXIS_BASES.includes(candidate.base)) throw new Error(`dual-axis: ${label} custom base must be ${AXIS_BASES.join(", ")}, received ${JSON.stringify(candidate.base)}`);
+	return {
+		kind: "custom",
+		base: candidate.base,
+		groups: groupIds(label, candidate.groups),
+		allow: pathList(label, "allow", candidate.allow),
+		deny: pathList(label, "deny", candidate.deny)
+	};
+}
+/**
+* Collect one `custom` axis's rule-group references. Only the speaker matters
+* here — an id is a name the settings page resolves, so this checks that the
+* list is a list of non-empty names and nothing more; whether the name exists is
+* decided at the moment of use ({@link resolveEffectiveAxes}), where a missing
+* one can be refused instead of quietly dropped.
+* @param label - the axis name used in the error message.
+* @param value - the untrusted `groups` value.
+* @returns the validated id list.
+* @throws When the value is not an array of non-empty strings.
+*/
+function groupIds(label, value) {
+	if (value === void 0) return [];
+	if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.length === 0)) throw new Error(`dual-axis: ${label} groups must be an array of non-empty rule-group ids`);
+	return [...new Set(value)];
+}
+/**
+* Read both axes out of one settings/config value.
+*
+* The parameter is UNTRUSTED on purpose: the same function serves the
+* composition layer's parsed Config, the settings service's projected
+* descriptor (an `unknown` on the wire between two packages), and a
+* hand-edited document, and none of those three is guaranteed to carry the
+* declared shape. Both axes therefore pass through {@link normalizeScope},
+* which is where an illegal value becomes a throw instead of an invented
+* boundary; a missing side falls back to the built-in default axis.
+* @param section - the section's current resolved value, whatever carries it.
+* @returns both axes.
+* @throws When either axis's shape is illegal.
+*/
+function axesOf(section) {
+	const declared = section === null || typeof section !== "object" ? {} : section;
+	return {
+		read: normalizeScope("read", unwrapVolatile(declared.read) ?? DEFAULT_READ_SCOPE),
+		write: normalizeScope("write", unwrapVolatile(declared.write) ?? DEFAULT_WRITE_SCOPE)
+	};
+}
+/**
+* Unwrap one config field's value.
+*
+* A `.volatile()` field is handed to the plugin as a cordis `Volatile<T>`
+* **accessor**, not as `T`: the schema's `get()` re-reads the stored value on
+* every call so an edit applies without remounting the entry. Reading the
+* property directly therefore yields the accessor object, whose `kind` is
+* `undefined` — which {@link normalizeScope} correctly refuses, failing the
+* whole row at mount. The upstream volatile Config
+* (`packages/core/agent-default-model/src/index.ts:68-71`) unwraps the same way.
+*
+* A hand-written config document may also carry the plain value, so both
+* spellings are accepted.
+* @param value - the configured field, as the accessor, as a plain value, or as
+*   whatever an untrusted document put under the key.
+* @returns the underlying value, or `undefined` when this field is unset.
+*/
+function unwrapVolatile(value) {
+	if (value === void 0) return void 0;
+	if (typeof value.get === "function") return value.get();
+	return value;
+}
+/**
+* This row's current value on the settings page, or `undefined` when no
+* settings service is mounted.
+*
+* This is the ONE read path to that row. It goes through `describe()` rather
+* than the config the plugin instance captured at mount because the loader does
+* not commit a later save back to that instance
+* (`vendor/loader/src/config/entry.ts:162-195`); `describe()` re-projects
+* `entry.fiber.config` and unwraps the volatile accessors on every call
+* (`packages/settings/settings/src/index.ts:319-323` +
+* `packages/settings/settings/src/schema.ts:11`), which is the same path the
+* settings page renders from. A save therefore applies without a restart.
+* @param ctx - host context; the service is looked up, never injected.
+* @returns the row's current value, or `undefined` when unavailable.
+*/
+function declaredSection(ctx) {
+	return ctx.get("settings")?.describe().find((row) => row.ns === DUAL_AXIS_ROW_ID)?.value;
+}
+/**
+* The group ids a newly created session starts out referencing.
+* @param section - the row's current value, as {@link declaredSection} returns it.
+* @returns the ids, deduplicated; empty when the row declares none.
+* @throws When a declared id is not a non-empty string.
+*/
+function defaultGroupIds(section) {
+	return groupIds("defaultGroups", section === null || typeof section !== "object" ? void 0 : unwrapVolatile(section.defaultGroups));
+}
+//#endregion
+//#region lib/types/groups.js
+/**
+* RULE GROUPS and THE ONE resolution from a session's axis preset to the ranges
+* actually in force.
+*
+* A rule group is a named fragment of path rules owned by the settings page
+* (`dual-axis`'s `groups` Config field). A session references groups BY ID and
+* never stores their content: ten sessions selecting one group must not become
+* ten copies of it, because copies drift. Resolving an id against the CURRENT
+* library is therefore the only place a group's rules enter a decision, and
+* editing a group takes effect on every session referencing it without a
+* restart.
+*
+* This module is that place, for both axes and for both invariants that ride on
+* them:
+*
+* - **deny wins over allow**, with session-level entries and every selected
+*   group merged into ONE allow list and ONE deny list first
+*   ({@link resolveEffectiveAxes}), so a group's removal cannot be overridden by
+*   a session-level addition.
+* - **write never exceeds read**: the effective write range is the write axis's
+*   range INTERSECTED with the read axis's range. A write outside the read range
+*   would let an agent overwrite a file it cannot read back, so the intersection
+*   is computed here — in the resolution — and never in a user interface.
+*
+* Both the fence and the model-facing prompt call {@link resolveEffectiveAxes},
+* so the range the model is told about and the range it is held to are the same
+* computation over the same inputs: the session's own preset (read and write
+* axes, their own additions and removals, and the group ids they selected) plus
+* the current definitions of those ids. The settings page's `read` / `write`
+* defaults and its `defaultGroups` seed are NOT among those inputs: they are
+* read once, when a session is created.
+*
+* A reference to an id the library does not define is refused, never treated as
+* an empty group: "I excluded it and nothing happened" is the worst failure this
+* surface can have.
+*
+* @module @t4r71/dsh-dual-axis/groups
+*/
+/** The narrowing that removed nothing. Exported: it is the stored record's absent value. */
+const NO_NARROWING = {
+	narrowed: false,
+	droppedRoots: [],
+	lostUnbounded: false
+};
+/**
+* Read one stored narrowing report, or throw naming the member that is
+* unreadable.
+*
+* An absent member is the legal "nothing was ever published for this record"
+* state and yields {@link NO_NARROWING}: that is exactly what the fence enforced
+* before this member existed, so the surface shows no narrowing rather than
+* inventing one. Anything PRESENT must be well formed — a report whose root list
+* cannot be read would otherwise be displayed as "nothing was removed".
+* @param value - the untrusted `narrowing` member of a stored record.
+* @returns the validated report.
+* @throws When the member is present and not a well-formed report.
+*/
+function parseNarrowing(value) {
+	if (value === void 0) return NO_NARROWING;
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("dual-axis: a stored narrowing report must be an object");
+	const candidate = value;
+	if (typeof candidate.narrowed !== "boolean" || typeof candidate.lostUnbounded !== "boolean") throw new Error("dual-axis: a stored narrowing report needs boolean narrowed and lostUnbounded");
+	return {
+		narrowed: candidate.narrowed,
+		droppedRoots: pathList("stored narrowing", "droppedRoots", candidate.droppedRoots),
+		lostUnbounded: candidate.lostUnbounded
+	};
+}
+/**
+* Attach the group ids a NEW session starts out referencing to the axes that are
+* `custom`, leaving every other axis exactly as declared.
+*
+* The rule is judged per axis, and only an axis whose OWN kind is `custom` can
+* carry a reference: checking the settings row instead (a tick that is not
+* tied to an axis) promoted `read: all` to `read: { kind: 'custom', base: 'all' }`
+* even though no axis was ever set to custom. An axis of one of the three closed
+* kinds has nowhere to put an id and is seeded verbatim — promoting it would
+* report a custom scope the settings page never showed.
+*
+* A group may carry rules for either axis or both, and the session selected it
+* once, so the same list goes on both `custom` axes; the group's `read` rules
+* then apply where they exist and its `write` rules where they exist. Two axes
+* are therefore independent: one may take the references while the other keeps
+* its closed kind.
+* @param axes - the pair a new session is seeded with.
+* @param ids - the settings page's `defaultGroups`.
+* @returns the pair carrying those references.
+*/
+function seedGroupReferences(axes, ids) {
+	if (ids.length === 0) return axes;
+	const attach = (axis) => axis.kind === "custom" ? {
+		...axis,
+		groups: [.../* @__PURE__ */ new Set([...axis.groups ?? [], ...ids])]
+	} : axis;
+	return {
+		read: attach(axes.read),
+		write: attach(axes.write)
+	};
+}
+//#endregion
+//#region lib/types/session-store.js
+/**
+* THE per-session axis store, outside the session log.
+*
+* The axes cannot live in a session's own log: this package's own event type is
+* not in 0.1.7's `KNOWN_SESSION_EVENT_TYPES`, and `Session.append` takes no
+* envelope option, so the event cannot be marked `ignorable` and a log carrying
+* it is refused WHOLE by `validateStoredEvents`
+* (`packages/session/session-persistence/src/storage-contract.ts:75-77`).
+* A session this package had written to could therefore not be opened at all
+* after a restart.
+*
+* The axes live instead in this package's OWN settings namespace,
+* `dual-axis-sessions`, partitioned by session id. That namespace is a
+* separate Loader entry from `dual-axis` because the row's namespace carries the
+* settings page's read/write/defaultGroups form: an undeclared field inside that
+* row would be projected into the row's form. This namespace declares exactly one
+* field and the settings page never renders it.
+*
+* `sandbox/mode` REMAINS the write axis's legal landing place in the log — see
+* `./session-axes.ts`, which mirrors the write base onto it. The log therefore
+* still records the containment the operating-system layer enforces; what it no
+* longer records is the path-level axis pair, which is this module's.
+*
+* A session with NO record is neither an error state nor a reason to hide a
+* control: every live decision path reads through {@link SessionAxesStore.ensure},
+* which answers {@link seedAxesFor} — the deployment seed a newly created session
+* is pinned with — and hands that SAME value to the ONE repair write it
+* schedules. Such a session therefore runs under the deployment's seed from its
+* first read, not under {@link DEFAULT_AXES} until the record lands, and the pair
+* a picker shows before the record exists is the pair the fence and the prompt
+* are already enforcing (the client half recomputes that seed from the same row —
+* see `sessionAxesSeed` in `@t4r71/dsh-dual-axis-ui`).
+* {@link DEFAULT_AXES} is now only the answer {@link SessionAxesStore.getOr} gives
+* a caller that holds no session to build a seed from.
+*
+* A session with no record that has ALSO never been used is a different case, and
+* it is the one the workspace picker creates every time: reopening the same
+* workspace reopens the same session id, so freezing it at creation would pin the
+* axes of a conversation nobody has had to whatever the settings row said that
+* day. Its record is therefore written when it is USED ({@link hasContent}), not
+* when it is created: until then every read recomputes the seed from the row as
+* it stands NOW, and the dropdown follows the settings page in real time.
+*
+* @module @t4r71/dsh-dual-axis/session-store
+*/
+/**
+* The settings namespace holding every session's axis pair. It is a Loader entry
+* id (`cordis.patch.yml`), which is what `SettingsForms.write` looks up.
+*/
+const SESSION_AXES_NAMESPACE = "dual-axis-sessions";
+/** The single Config field: session id -> axis pair. */
+const SESSION_AXES_FIELD = "axes";
+/**
+* This entry's composition config. The field is `.volatile()` because 0.1.7
+* refuses an entry with no volatile field outright
+* (`packages/settings/settings/src/index.ts:385-386`) and because path writes
+* are refused for every non-volatile path (`:387-389`).
+*
+* `z.dict(z.any())` rather than a per-session object schema: the keys are session
+* ids, which no schema can enumerate, and the VALUES are validated by
+* {@link parseSessionAxesField}, where an unreadable axis becomes a throw rather
+* than an invented boundary — the same rule the row's own axes follow.
+*
+* Annotated rather than inferred: `z.dict`'s output names `Dict` from
+* `@deepseek-ai/cosmokit`, and declaration emit refuses a type it can only reach
+* through a nested `node_modules` path (TS2883). The annotation states the same
+* type through that package's own entry.
+*/
+const Config = z.object({ axes: z.dict(z.any()).default({}).volatile() });
+/**
+* The pair {@link SessionAxesStore.getOr} answers for a session with no stored
+* record, and nothing else.
+*
+* It is deliberately NOT what a session with no record is held to any more:
+* every live read goes through {@link SessionAxesStore.ensure}, which answers the
+* deployment's seed ({@link seedAxesFor}), so the pair in force is the pair the
+* session was created with rather than the built-in one. Reaching for this
+* constant on a decision path would hold a session to a boundary the settings
+* page never chose — narrower than an `all` default, wider than a `deny` one.
+* @see SessionAxesStore.getOr
+*/
+const DEFAULT_AXES = {
+	read: DEFAULT_READ_SCOPE,
+	write: DEFAULT_WRITE_SCOPE
+};
+/**
+* The axis pair a session with no stored record is REPAIRED to — the same seed a
+* newly created session is pinned with.
+*
+* Repairing to the standing pair instead (`DEFAULT_AXES`) would be narrower but wrong: a
+* session whose creation-time write was lost would keep the built-in defaults
+* for the rest of its life, and the settings page's seed would never reach it.
+* Repairing to the seed keeps `pin`'s retry semantics intact — the retry just
+* happens on the next touch of the session instead of only at creation.
+*
+* The seed is computed from two synchronous reads: the settings row's
+* `read`/`write`/`defaultGroups` (seeds for a session that has none of its own)
+* and, for a subagent child, the parent's pair AS IT STANDS NOW. A parent with
+* no record of its own yields `undefined` from {@link inheritedAxes}, which is
+* the same answer `pin` gets, so parent and child agree in that case too.
+* @param ctx - host context; carries the settings service the seed is read from.
+* @param session - the session to seed.
+* @param fallback - the composing plugin's own config, used only when no settings
+*   service is mounted (where the namespace cannot be written anyway).
+* @returns the pair a newly created session would have been pinned with.
+*/
+function seedAxesFor(ctx, session, fallback) {
+	const section = declaredSection(ctx);
+	const inherited = inheritedAxes(ctx, session);
+	if (section === void 0) return seedGroupReferences(inherited ?? fallback?.axes ?? DEFAULT_AXES, fallback?.groups ?? []);
+	return seedPair(section, inherited);
+}
+/**
+* The pure core of {@link seedAxesFor}: one settings row value, plus the pair a
+* subagent child inherits, into the pair a session with no record is seeded with.
+*
+* It is TOTAL on purpose, and the client half mirrors it step for step
+* (`sessionAxesSeed` in `@t4r71/dsh-dual-axis-ui`, pinned by
+* `tests/seed-parity.spec.ts`): an unreadable row, and an unreadable inherited
+* pair, answer {@link DEFAULT_AXES}. That is also what a live read answers — see
+* {@link SessionAxesStore.ensure} — so the pair a picker shows for a session with
+* no record and the pair the host enforces are one value rather than two.
+* @param row - the settings row's value, untrusted: a human may have edited it.
+* @param inherited - the parent's pair for a subagent child, or `undefined`.
+* @returns the seed pair.
+*/
+function seedPair(row, inherited) {
+	try {
+		return seedGroupReferences(inherited === void 0 ? axesOf(row) : pairOf(inherited), defaultGroupIds(row));
+	} catch {
+		return DEFAULT_AXES;
+	}
+}
+/**
+* Re-normalize a pair another reader produced.
+*
+* A pair this package stored is already normalized; a hand-edited document's is
+* not, and the inherited pair the client half reads comes straight off the wire.
+* Running both through the same validation is what makes the two halves agree on
+* the bytes, not merely on the kinds.
+* @param pair - the untrusted pair.
+* @returns the normalized pair.
+* @throws When either member is not a legal axis value.
+*/
+function pairOf(pair) {
+	return {
+		read: normalizeScope("read", pair.read),
+		write: normalizeScope("write", pair.write)
+	};
+}
+/**
+* The pair a **subagent child session** inherits, or `undefined` when this is not
+* a child or its parent holds no record.
+*
+* A child does not read the settings page: 0.1.7 deliberately seeds a child with
+* its parent's explicit per-session override, and the parent's STORED pair is the
+* only copy of that override this package has. Returning `undefined` (rather than
+* inventing one) leaves the caller on the settings seed, which is what the child
+* would have received had the parent never overridden anything — and is exactly
+* the pair an un-recorded parent is itself held to.
+*
+* The record is looked up by the id the child's header names. The parent's own
+* Session object is NOT required: requiring it made the answer depend on whether
+* the parent happened to be resident in this process, and the client half — which
+* reads the same document by the same id — cannot observe residency, so the two
+* would disagree for a child whose parent is not materialized.
+* @param ctx - host context carrying the axis store.
+* @param session - the session whose parent to read.
+* @returns the parent's pair, or `undefined`.
+*/
+function inheritedAxes(ctx, session) {
+	if (session.header.origin !== "subagent") return void 0;
+	const parentId = session.header.parentSession;
+	if (parentId === void 0) return void 0;
+	return sessionAxesStore(ctx).get(String(parentId));
+}
+/** How many times one write re-reads the revision after a conflict. */
+const AXES_WRITE_ATTEMPTS = 4;
+/** Milliseconds before attempt N is issued, N counted from zero. */
+const AXES_WRITE_BACKOFF_MS = [
+	0,
+	25,
+	75,
+	200
+];
+/**
+* A whole-document write was refused because another writer moved the settings
+* document between this writer's read and its write.
+*
+* It is thrown, never swallowed: the axis a person just picked is not in force
+* unless it was stored, and reporting success for a lost write would leave the
+* fence enforcing a range the picker does not show.
+*/
+var SessionAxesConflictError = class extends Error {
+	/** Stable machine code for callers that map failures to their own taxonomy. */
+	code = "DUAL_AXIS_AXES_CONFLICT";
+	/** The namespace whose write was refused. */
+	ns = SESSION_AXES_NAMESPACE;
+	/** Attempts made before giving up. */
+	attempts;
+	/**
+	* @param cause - the last conflict the settings service raised.
+	* @param attempts - attempts made before giving up.
+	*/
+	constructor(cause, attempts) {
+		super("dual-axis: the settings document changed under this writer " + String(attempts) + " times while storing a session axis pair; nothing was written", { cause });
+		this.name = "SessionAxesConflictError";
+		this.attempts = attempts;
+	}
+};
+/**
+* Whether two narrowing reports say the same thing, so a republish that changes
+* nothing does not write the document.
+* @param left - one report, absent when nothing was ever published.
+* @param right - the other, absent under the same condition.
+* @returns whether both report the same removal.
+*/
+function sameNarrowing(left, right) {
+	if (left === void 0 || right === void 0) return false;
+	return left.narrowed === right.narrowed && left.lostUnbounded === right.lostUnbounded && left.droppedRoots.length === right.droppedRoots.length && left.droppedRoots.every((root) => right.droppedRoots.includes(root));
+}
+/**
+* Whether a value is a plain data object.
+* @param value - the candidate.
+* @returns whether it is an object that is not null and not an array.
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Read one stored record into an axis pair, or throw naming the member that is
+* unreadable.
+* @param id - the session id the record belongs to, for the error message.
+* @param value - the untrusted record.
+* @returns the validated pair.
+* @throws When either member is not a legal axis value.
+*/
+function parseSessionAxesRecord(id, value) {
+	if (!isRecord(value)) throw new Error("dual-axis: the stored axes of session " + JSON.stringify(id) + " must be an object");
+	const narrowing = parseNarrowing(value.narrowing);
+	return {
+		read: normalizeScope("read", value.read ?? DEFAULT_READ_SCOPE),
+		write: normalizeScope("write", value.write ?? DEFAULT_WRITE_SCOPE),
+		...narrowing.narrowed ? { narrowing } : {}
+	};
+}
+/**
+* Read the whole stored field. A human may have edited the settings document, so
+* an unreadable entry throws instead of being dropped: dropping it would silently
+* widen that session back to the deployment defaults.
+* @param value - the untrusted `axes` field.
+* @returns every stored pair, by session id.
+* @throws When the field is not an object of readable records.
+*/
+function parseSessionAxesField(value) {
+	if (value === void 0 || value === null) return {};
+	if (!isRecord(value)) throw new Error("dual-axis: the stored session axes field must be an object");
+	const parsed = {};
+	for (const [id, record] of Object.entries(value)) parsed[id] = parseSessionAxesRecord(id, record);
+	return parsed;
+}
+/**
+* The stored pair as this package spells it everywhere else. The stored record is
+* already a pair; this exists so the store's return type is the shared one and a
+* caller cannot start depending on the record's identity.
+* @param record - the stored pair.
+* @returns the same pair.
+*/
+function scopesOf(record) {
+	return {
+		read: record.read,
+		write: record.write
+	};
+}
+/**
+* The read and write face of {@link SESSION_AXES_NAMESPACE}, plus the sweep that
+* keeps it from growing with the sessions that no longer exist.
+*
+* Reads go through `settings.describe()`, the same projection the settings page
+* renders from, and are memoized on the namespace's `revision` — which 0.1.7 bumps
+* exactly when that entry's stored profile override changes
+* (`packages/settings/settings/src/index.ts:311-317`). A decision path therefore
+* pays one `describe()` per document change, not one per tool dispatch.
+*/
+var SessionAxesStore = class {
+	ctx;
+	options;
+	cachedRevision;
+	cachedRecords = {};
+	/** Parsed records by the JSON spelling that produced them. */
+	bySpelling = /* @__PURE__ */ new Map();
+	/**
+	* Session ids with a repair write outstanding (or already landed) since the
+	* record was found missing. Prevents one repair per tool dispatch while the
+	* whole-document write is in flight; cleared when a write FAILS so the next
+	* touch retries instead of leaving the session on the defaults forever.
+	*/
+	repairing = /* @__PURE__ */ new Set();
+	/**
+	* The last narrowing report this store handed to a write, by session id. A
+	* decision path re-resolves on every touch, so this is what keeps it from
+	* queueing the same document write over and over; it is cleared when a write
+	* lands (or fails), never on a read.
+	*/
+	narrowingMemo = /* @__PURE__ */ new Map();
+	/** Sessions with a narrowing write outstanding right now. */
+	narrowingWriting = /* @__PURE__ */ new Set();
+	/**
+	* @param ctx - host context; the settings service is looked up, never injected,
+	*   so a composition without settings still loads this package's fence.
+	* @param options - retry policy and the sleep used between attempts.
+	*/
+	constructor(ctx, options = {}) {
+		this.ctx = ctx;
+		this.options = {
+			attempts: options.attempts ?? 4,
+			backoffMs: options.backoffMs ?? AXES_WRITE_BACKOFF_MS,
+			sleep: options.sleep ?? ((ms) => new Promise((resolve) => {
+				setTimeout(resolve, ms);
+			}))
+		};
+	}
+	/**
+	* This namespace's current settings row, or `undefined` when no settings
+	* service is mounted or the entry is not composed.
+	* @returns the descriptor carrying the value and the revision.
+	*/
+	descriptor() {
+		const settings = this.ctx.get("settings");
+		if (settings === void 0) return void 0;
+		return settings.describe().find((row) => row.ns === SESSION_AXES_NAMESPACE);
+	}
+	/**
+	* Every stored pair, by session id.
+	* @returns the parsed field.
+	* @throws When the document carries an unreadable record.
+	*/
+	records() {
+		const descriptor = this.descriptor();
+		if (descriptor === void 0) return {};
+		if (descriptor.revision === this.cachedRevision) return this.cachedRecords;
+		const value = isRecord(descriptor.value) ? descriptor.value[SESSION_AXES_FIELD] : void 0;
+		const spelling = JSON.stringify(value ?? null);
+		let records = this.bySpelling.get(spelling);
+		if (records === void 0) {
+			records = parseSessionAxesField(value);
+			this.bySpelling.set(spelling, records);
+		}
+		this.cachedRevision = descriptor.revision;
+		this.cachedRecords = records;
+		return records;
+	}
+	/**
+	* One session's stored pair.
+	* @param sessionId - the session whose axes to read.
+	* @returns the pair, or `undefined` when this session has no record yet.
+	*/
+	get(sessionId) {
+		const record = this.records()[sessionId];
+		return record === void 0 ? void 0 : scopesOf(record);
+	}
+	/**
+	* One session's stored pair, or the built-in defaults.
+	*
+	* The answer for a caller that has no session to build a seed from, and the only
+	* remaining reader of {@link DEFAULT_AXES}. Every live path reads {@link ensure}
+	* instead, whose un-recorded answer is the session's own seed.
+	* @param sessionId - the session whose axes to read.
+	* @returns the pair in force.
+	*/
+	getOr(sessionId) {
+		return this.get(sessionId) ?? DEFAULT_AXES;
+	}
+	/**
+	* One session's pair, with an un-recorded session scheduled for repair.
+	*
+	* This is the read every LIVE touch point uses (the model-facing prompt, the
+	* read fence, and `/axis`). A session that has a record answers it; a session
+	* that has none answers {@link seedAxesFor} — the pair `pin` writes for a newly
+	* created session — and that ONE value is both this read's answer and what the
+	* scheduled repair stores. The answer and the write therefore cannot disagree,
+	* and a session created under a saved default runs under that default from its
+	* FIRST turn instead of waiting for the record to land. The record is what
+	* answers from the moment it lands.
+	*
+	* An un-recorded session is only REPAIRED when it has been used
+	* ({@link hasContent}). Until then the seed is recomputed on every read, so the
+	* settings row stays live: a session the workspace picker reopens before anyone
+	* has sent anything follows the settings page, which is the whole point of not
+	* having a record yet. The moment a turn lands, the next read repairs the
+	* session and it freezes — the same seed it answered with, computed from the row
+	* as it then stood.
+	*
+	* The seed is a thunk because only the caller can build it (it needs the
+	* session, and the composing plugin's config for a settings-less host). It is
+	* evaluated exactly once per un-recorded read — those reads are a prompt
+	* assembly, a tool dispatch and a pick, never a hot loop — and it must have no
+	* side effect, because its value IS this read's answer.
+	* @param sessionId - the session whose axes to read.
+	* @param seed - builds the pair a repair persists AND this read answers; never
+	*   called when a record exists.
+	* @param frozen - whether the session has been used, so its pair must be
+	*   written rather than recomputed. Defaults to `true`: a caller that cannot
+	*   judge the session's content keeps the pre-existing freeze-on-first-touch
+	*   behaviour, which is the safe direction — it never widens a live session's
+	*   axes behind the person's back.
+	* @returns the pair in force right now.
+	*/
+	ensure(sessionId, seed, frozen = true) {
+		const standing = this.get(sessionId);
+		if (standing !== void 0) return standing;
+		let seeded;
+		try {
+			seeded = seed();
+		} catch {
+			if (frozen) this.scheduleRepair(sessionId, seed);
+			return DEFAULT_AXES;
+		}
+		if (frozen) this.scheduleRepair(sessionId, () => seeded);
+		return seeded;
+	}
+	/**
+	* Publish the narrowing a live read just resolved, when the record does not
+	* already carry it.
+	*
+	* This is how the client half learns what the read axis removed from the write
+	* range without re-implementing the path algebra: it reads this member out of
+	* the same document its two dropdowns already read. The value comes from the
+	* very resolution the prompt and the fence used, so the surfaced narrowing and
+	* the enforced one are one computation rather than two that must agree.
+	*
+	* Called on every touch of a session that references groups, so an edit to a
+	* group's rules is republished by the next touch instead of waiting for the
+	* record to be rewritten for another reason. A session with no record is left
+	* alone: its axes are recomputed from the settings row on every read, and a
+	* store of its own would freeze that. Writes are fire-and-forget — a caller is
+	* a synchronous decision path and its answer must not depend on a document
+	* write.
+	* @param sessionId - the session whose narrowing to publish.
+	* @param narrowing - the value {@link resolveEffectiveAxes} returned for it.
+	*/
+	refreshNarrowing(sessionId, narrowing) {
+		const record = this.records()[sessionId];
+		if (record === void 0) return;
+		const stored = record.narrowing;
+		if (stored === void 0 && !narrowing.narrowed) return;
+		if (sameNarrowing(stored, narrowing)) {
+			this.narrowingMemo.delete(sessionId);
+			return;
+		}
+		if (sameNarrowing(this.narrowingMemo.get(sessionId), narrowing)) return;
+		this.narrowingMemo.set(sessionId, narrowing);
+		this.writeNarrowing(sessionId, narrowing);
+	}
+	/**
+	* Store one narrowing report for a session that already has a record, at most
+	* once per value.
+	*
+	* A failed write only forgets what was attempted: the next touch republishes
+	* the same report, and the dropdowns keep showing the last stored one instead
+	* of nothing. It never touches the axes, so a refresh that loses its race
+	* cannot revert a pick.
+	* @param sessionId - the session to update.
+	* @param narrowing - the report to store.
+	*/
+	writeNarrowing(sessionId, narrowing) {
+		if (this.narrowingWriting.has(sessionId)) return;
+		this.narrowingWriting.add(sessionId);
+		Promise.resolve().then(async () => {
+			const record = this.records()[sessionId];
+			if (record === void 0) return;
+			const stored = record.narrowing;
+			if (stored === void 0 && !narrowing.narrowed) return;
+			if (sameNarrowing(stored, narrowing)) return;
+			const { narrowing: _retired, ...axes } = record;
+			await this.replaceRecords({
+				...this.records(),
+				[sessionId]: {
+					...axes,
+					...narrowing.narrowed ? { narrowing } : {}
+				}
+			});
+		}).catch((error) => {
+			this.ctx.logger?.warn("dual-axis: could not store the narrowing of session \"%s\"; the dropdowns keep the last stored report", sessionId);
+			this.ctx.logger?.warn(error);
+		}).finally(() => {
+			this.narrowingWriting.delete(sessionId);
+			this.narrowingMemo.delete(sessionId);
+		});
+	}
+	/**
+	* Store one session's pair, whole-document, and report a lost write loudly.
+	*
+	* A single `replace` of the field: removal needs the whole map anyway, and a
+	* per-id path write cannot prune. Every attempt re-reads the revision, so an
+	* edit that landed between the read and the write is retried against the value
+	* it produced instead of being overwritten from a stale snapshot.
+	* @param sessionId - the session the pair belongs to.
+	* @param axes - the pair to store.
+	* @throws {SessionAxesConflictError} when every attempt lost the revision race.
+	* @throws When no settings service serves this namespace.
+	*/
+	async set(sessionId, axes, narrowing) {
+		await this.replaceRecords({
+			...this.records(),
+			[sessionId]: {
+				read: axes.read,
+				write: axes.write,
+				...narrowing === void 0 || !narrowing.narrowed ? {} : { narrowing }
+			}
+		});
+		if (narrowing !== void 0) this.narrowingMemo.set(sessionId, narrowing);
+	}
+	/**
+	* Persist one un-recorded session's seed, at most once until it lands.
+	*
+	* Fire-and-forget on purpose: every caller is a synchronous decision path
+	* (a tool dispatch, a prompt assembly) that cannot await a whole-document
+	* write, and none of them may fail because the repair could not be stored —
+	* the answer that read already gave stands either way. A failed repair is
+	* logged and re-armed.
+	* @param sessionId - the session to repair.
+	* @param seed - builds the pair to persist; may throw on an unreadable document.
+	*/
+	scheduleRepair(sessionId, seed) {
+		if (this.repairing.has(sessionId)) return;
+		this.repairing.add(sessionId);
+		Promise.resolve().then(async () => {
+			if (this.get(sessionId) !== void 0) return;
+			await this.set(sessionId, seed());
+			this.repairing.delete(sessionId);
+		}).catch((error) => {
+			this.repairing.delete(sessionId);
+			this.ctx.logger?.warn("dual-axis: could not store the axes of session \"%s\"; it stays on the default pair", sessionId);
+			this.ctx.logger?.warn(error);
+		});
+	}
+	/**
+	* Prune records whose session no longer exists.
+	*
+	* The deletion signal is the persistence layer itself: a session whose id is
+	* absent from `sessionPersistence.list()` has no stored log. `session/disposed`
+	* is NOT that signal — residency churn disposes a session whose file is still on
+	* disk, and dropping its axes there would silently reset a session that is about
+	* to be resumed.
+	* @returns the ids dropped, or `undefined` when the sweep cannot judge (no
+	*   persistence service mounted, or a listing failed): an unjudgeable sweep
+	*   removes nothing.
+	*/
+	async sweep() {
+		const records = this.records();
+		const ids = Object.keys(records);
+		if (ids.length === 0) return {
+			removed: [],
+			before: 0
+		};
+		const persistence = this.ctx.get("sessionPersistence");
+		if (persistence === void 0) return void 0;
+		let live;
+		try {
+			const listed = await persistence.list();
+			live = new Set(listed.map((snapshot) => String(snapshot.header.id)));
+		} catch (error) {
+			this.ctx.logger?.warn("dual-axis: could not list stored sessions, keeping every axis record");
+			this.ctx.logger?.warn(error);
+			return;
+		}
+		const kept = {};
+		const removed = [];
+		for (const id of ids) {
+			const record = records[id];
+			if (record === void 0) continue;
+			if (live.has(id)) kept[id] = record;
+			else removed.push(id);
+		}
+		if (removed.length === 0) return {
+			removed: [],
+			before: ids.length
+		};
+		await this.replaceRecords(kept);
+		return {
+			removed,
+			before: ids.length
+		};
+	}
+	/**
+	* Replace the whole field, retrying while the revision fence refuses it.
+	* @param records - the complete next field.
+	* @throws {SessionAxesConflictError} when every attempt was refused.
+	*/
+	async replaceRecords(records) {
+		const settings = this.ctx.get("settings");
+		const entryExists = this.descriptor() !== void 0;
+		if (settings === void 0 || !entryExists) throw new Error("dual-axis: no configurable plugin entry \"dual-axis-sessions\"; the session axis store cannot be written");
+		let conflict;
+		for (let attempt = 0; attempt < this.options.attempts; attempt += 1) {
+			const backoff = this.options.backoffMs[attempt] ?? this.options.backoffMs[this.options.backoffMs.length - 1] ?? 0;
+			if (backoff > 0) await this.options.sleep(backoff);
+			const revision = this.descriptor()?.revision;
+			try {
+				await settings.replace(SESSION_AXES_NAMESPACE, { [SESSION_AXES_FIELD]: records }, revision);
+				return;
+			} catch (error) {
+				conflict = error;
+			}
+		}
+		throw new SessionAxesConflictError(conflict, this.options.attempts);
+	}
+};
+/** Stores by host context, so every consumer of one process shares one cache. */
+const stores = /* @__PURE__ */ new WeakMap();
+/**
+* The store of one host context. Consumers hold no service of their own: the
+* fence and the prompt must keep working in a composition that never mounted the
+* settings service, where the store simply has nothing to read.
+* @param ctx - host context.
+* @returns the shared store.
+*/
+function sessionAxesStore(ctx) {
+	const existing = stores.get(ctx);
+	if (existing !== void 0) return existing;
+	const created = new SessionAxesStore(ctx);
+	stores.set(ctx, created);
+	return created;
+}
+/**
+* This entry's plugin body.
+*
+* The entry exists for its Config: `SettingsForms.describe` projects the schemas
+* of LOADED entries, so the session axis store has no namespace to live in until
+* a Loader row activates with this plugin. The body itself does nothing — every
+* read and write goes through {@link SessionAxesStore}, which the composing
+* plugin owns.
+* @returns nothing.
+*/
+async function apply() {}
+/**
+* The Loader entry's value: the no-op apply carrying the Config the registry
+* reads off the plugin value itself. Spelled as an interface for the same reason
+* {@link Config} is annotated — the inferred type of `Object.assign(apply, {
+* Config })` names `Dict` from `@deepseek-ai/cosmokit`, which declaration emit
+* cannot reach by name.
+*/
+const entry = Object.assign(apply, { Config });
+Object.defineProperty(apply, "name", {
+	value: "dual-axis-sessions",
+	configurable: true
+});
+//#endregion
+export { AXES_WRITE_ATTEMPTS, AXES_WRITE_BACKOFF_MS, Config, DEFAULT_AXES, SESSION_AXES_FIELD, SESSION_AXES_NAMESPACE, SessionAxesConflictError, SessionAxesStore, entry as default, inheritedAxes, parseSessionAxesField, parseSessionAxesRecord, seedAxesFor, seedPair, sessionAxesStore };