@hasna-internal/kai-settings 0.1.1-rc.2

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hasna-internal/kai-settings`.
+ * @module @hasna-internal/kai-settings/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "settings-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,41 @@
+/**
+ * Package-owned invariant companion for `@hasna-internal/kai-settings`.
+ * @module @hasna-internal/kai-settings/invariant
+ */
+import { deepEqualJson } from "./index.js";
+const PACKAGE_NAME = '@hasna-internal/kai-settings';
+/** Cordis companion plugin name. */
+export const name = 'settings-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * Install the commit-event contract: `settings/updated` fires only for a
+ * currently registered namespace, only when the resolved value changed, and
+ * only with the service's authoritative resolved value — all judged with the
+ * seam's own equality predicate.
+ */
+const install = (ctx, fail) => {
+    ctx.on('settings/updated', (ns, next, prev) => {
+        const settings = ctx.get('settings');
+        if (settings === undefined) {
+            fail(`settings/updated for "${ns}" emitted without a live settings service`);
+        }
+        const current = settings.get(ns);
+        if (current === undefined) {
+            fail(`settings/updated for "${ns}" emitted while the namespace is unregistered`);
+        }
+        if (!deepEqualJson(current, next)) {
+            fail(`settings/updated for "${ns}" does not match the authoritative resolved value`);
+        }
+        if (deepEqualJson(next, prev)) {
+            fail(`settings/updated for "${ns}" emitted without a resolved-value change`);
+        }
+    });
+};
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//# sourceMappingURL=invariant.js.map

package/lib/types/redact.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Structural secret redaction for settings values. `role('secret')` fields are
+ * removed from a value before it crosses a wire boundary; a sidecar records
+ * each schema-declared secret position and whether it currently holds a value,
+ * so a configuration surface can render a write-only input without ever
+ * receiving the secret itself.
+ * @module @hasna-internal/kai-settings/redact
+ */
+import type z from '@deepseek-ai/schemastery';
+/** One schema-declared secret position inside a redacted value. */
+export interface RedactedSecret {
+    /** Path from the section root to the removed field (concrete dict keys and array indexes included). */
+    path: string[];
+    /** Whether the field held a value before redaction. */
+    set: boolean;
+}
+/** A value with every `role('secret')` field removed, plus the removal record. */
+export interface RedactedValue {
+    /** Detached copy of the input with secret fields absent. */
+    value: unknown;
+    /**
+     * Every reachable secret position: object properties always (even unset, so
+     * a form knows the slot exists), dict entries and array items only where the
+     * value has them.
+     */
+    secrets: RedactedSecret[];
+}
+/**
+ * Remove every `role('secret')` field a schema declares from a value. The
+ * walker follows `object`, `dict`, and `array` containers; a secret must be
+ * declared directly on a field reachable through those containers (a secret
+ * buried inside a union branch or transform is not reachable and must not be
+ * modeled that way). The input is never mutated.
+ * @param schema - live schemastery schema describing the value.
+ * @param value - the value to strip; `undefined` yields an empty record with
+ *   object-property secret slots still enumerated.
+ * @returns the stripped detached value and the ordered secret positions.
+ */
+export declare function redactSecrets(schema: z<never>, value: unknown): RedactedValue;
+//# sourceMappingURL=redact.d.ts.map

package/lib/types/redact.js

@@ -0,0 +1,78 @@
+/**
+ * Structural secret redaction for settings values. `role('secret')` fields are
+ * removed from a value before it crosses a wire boundary; a sidecar records
+ * each schema-declared secret position and whether it currently holds a value,
+ * so a configuration surface can render a write-only input without ever
+ * receiving the secret itself.
+ * @module @hasna-internal/kai-settings/redact
+ */
+/** Whether a value is a plain data object the walker may recurse into. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function walk(node, value, path, secrets) {
+    if (node === undefined)
+        return value;
+    if (node.meta?.role === 'secret') {
+        secrets.push({ path, set: value !== undefined });
+        return undefined;
+    }
+    switch (node.type) {
+        case 'object': {
+            const properties = node.dict ?? {};
+            const source = isRecord(value) ? value : undefined;
+            const rebuilt = {};
+            if (source !== undefined) {
+                for (const [key, entry] of Object.entries(source)) {
+                    if (key in properties)
+                        continue;
+                    rebuilt[key] = entry;
+                }
+            }
+            for (const [key, child] of Object.entries(properties)) {
+                const stripped = walk(child, source?.[key], [...path, key], secrets);
+                if (stripped !== undefined)
+                    rebuilt[key] = stripped;
+            }
+            return source === undefined && Object.keys(rebuilt).length === 0 ? value : rebuilt;
+        }
+        case 'dict': {
+            if (!isRecord(value))
+                return value;
+            const rebuilt = {};
+            for (const [key, entry] of Object.entries(value)) {
+                const stripped = walk(node.inner, entry, [...path, key], secrets);
+                if (stripped !== undefined)
+                    rebuilt[key] = stripped;
+            }
+            return rebuilt;
+        }
+        case 'array': {
+            if (!Array.isArray(value))
+                return value;
+            return value.map((entry, index) => walk(node.inner, entry, [...path, String(index)], secrets));
+        }
+        default:
+            // TODO(settings-wire-redaction): Fail closed instead — a secret reachable
+            // only through a union, intersection, or transform is returned verbatim
+            // here, with nothing recording that it was missed.
+            return value;
+    }
+}
+/**
+ * Remove every `role('secret')` field a schema declares from a value. The
+ * walker follows `object`, `dict`, and `array` containers; a secret must be
+ * declared directly on a field reachable through those containers (a secret
+ * buried inside a union branch or transform is not reachable and must not be
+ * modeled that way). The input is never mutated.
+ * @param schema - live schemastery schema describing the value.
+ * @param value - the value to strip; `undefined` yields an empty record with
+ *   object-property secret slots still enumerated.
+ * @returns the stripped detached value and the ordered secret positions.
+ */
+export function redactSecrets(schema, value) {
+    const secrets = [];
+    const stripped = walk(schema, value, [], secrets);
+    return { value: stripped, secrets };
+}
+//# sourceMappingURL=redact.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Client-safe type surface of the user-settings seam: the namespace brand, the
+ * commit-origin union, and the seam's Cordis event declarations. Types only —
+ * no runtime code, and nothing here reaches a Host-only symbol, so a Client
+ * compilation face reads exactly the signatures the Host emits.
+ *
+ * @module @hasna-internal/kai-settings/types
+ */
+import type { Branded } from '@hasna-internal/kai-brand';
+/** Nominal id of one registered settings namespace. */
+export type SettingsNamespace = Branded<'SettingsNamespace'>;
+/** Origin of one committed settings change. */
+export type SettingsUpdateSource = 'update' | 'provider';
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        /**
+         * Committed change to one registered namespace's resolved value. Emitted
+         * after the provider persisted (for `update`) or published (`provider`)
+         * the change; never emitted when the resolved value is deep-equal.
+         * Listener failures are contained and logged — a sync throw and an async
+         * rejection alike — except `INVARIANT`-coded failures, which rethrow
+         * after every listener ran; that rethrow reaches the emitter only from
+         * synchronous listeners, so invariant checks on this event must not be
+         * async functions.
+         * @param ns - the namespace whose resolved value changed.
+         * @param next - the new resolved value.
+         * @param prev - the previous resolved value.
+         * @param source - whether the change entered through `update()` or the provider.
+         * @mode emit
+         */
+        'settings/updated'(ns: SettingsNamespace, next: unknown, prev: unknown, source: SettingsUpdateSource): void;
+        /**
+         * One registered namespace's RAW user section changed, whether or not the
+         * resolved value did. `settings/updated` is the consumer-facing event and
+         * stays deep-equal-gated; this one exists for configuration surfaces,
+         * which must learn that a field went from inherited to overridden (same
+         * resolved value, different meaning) and that their held revision is
+         * stale. Listener containment matches `settings/updated`.
+         * @param ns - the namespace whose stored section changed.
+         * @param revision - the namespace's new revision.
+         * @mode emit
+         */
+        'settings/document-updated'(ns: SettingsNamespace, revision: number): void;
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,10 @@
+/**
+ * Client-safe type surface of the user-settings seam: the namespace brand, the
+ * commit-origin union, and the seam's Cordis event declarations. Types only —
+ * no runtime code, and nothing here reaches a Host-only symbol, so a Client
+ * compilation face reads exactly the signatures the Host emits.
+ *
+ * @module @hasna-internal/kai-settings/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@hasna-internal/kai-settings",
+  "description": "Abstract user-settings seam (ctx.settings) for the DeepSeek Harness",
+  "version": "0.1.1-rc.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/settings/settings"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
+    "@hasna-internal/kai-brand": "^0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "@hasna-internal/kai-brand": "^0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2"
+  }
+}