@try-works/dsh-model-as-tool 0.1.3 → 0.3.6

package/node_modules/@try-works/tool-mode-extension-sdk/lib/install/update-flow.d.ts

@@ -0,0 +1,185 @@
+/**
+ * EXT-30 staged update and rollback (slices 1+2 of the approved design,
+ * docs/tool-mode/EXT-30-UPDATE-DESIGN.md).
+ *
+ * The two properties this module exists to enforce:
+ *
+ * - **Side-by-side, never in place.** A new version is fetched into
+ *   `staging/`, validated as DATA (manifest, integrity, schema/license/
+ *   permission deltas, structural-static self-tests), approved by an operator,
+ *   and only then promoted to its OWN version directory. The currently active
+ *   version's bytes are never mutated.
+ * - **The active version is a POINTER, committed atomically.** The profile
+ *   state document carries `activeVersions`/`previousVersions` maps written by
+ *   the store's single atomic writer under the store lock. Rollback restores
+ *   the pointer; it never copies bytes over a live install, never re-enables
+ *   disabled tools, never undoes revocations (those facts live beside the
+ *   pointer and are not touched).
+ *
+ * A post-commit rebind failure rolls the pointer back AUTOMATICALLY and names
+ * the reason. A corrupted version directory fails closed everywhere.
+ *
+ * Slice 1's self-tests are STRUCTURAL/STATIC only (manifest, referenced files,
+ * schema JSON parses): host-executed self-tests arrive with slice 3, and this
+ * module never executes extension code.
+ *
+ * @module @try-works/tool-mode-extension-sdk/install/update-flow
+ */
+import { type ArchiveSource, type InstallLimits, type InstallSource } from './staged.ts';
+/** One schema compatibility finding (EXT-30's schema recheck). */
+export interface SchemaDelta {
+    readonly toolName: string;
+    readonly file: 'input' | 'output';
+    /** True when a pinned composition would silently change meaning. */
+    readonly breaking: boolean;
+    readonly detail: string;
+}
+/** The staged update's validation report (EXT-30's gates, slice 1). */
+export interface UpdateValidationReport {
+    readonly manifestOk: boolean;
+    /** The current version the deltas were computed against. */
+    readonly comparedAgainst: string;
+    readonly schemaDeltas: readonly SchemaDelta[];
+    /** Set when the manifest licence declaration changed. */
+    readonly licenseDelta?: string;
+    /** Permission EXPANSIONS, one entry per expansion (AT-35). */
+    readonly permissionDeltas: readonly string[];
+    readonly selfTests: {
+        readonly kind: 'structural-static';
+        readonly passed: boolean;
+        readonly detail: string;
+    };
+    /** True when an operator approval is required before the commit. */
+    readonly requiresApproval: boolean;
+}
+/** The outcome of a successful stage (nothing is visible or active yet). */
+export interface UpdateStageResult {
+    readonly extensionId: string;
+    readonly stagedVersion: string;
+    /** Absolute path of the staged extraction (not the installed pool). */
+    readonly stagedPath: string;
+    readonly report: UpdateValidationReport;
+}
+/** The outcome of a commit (the pointer moved; the old pointer is the rollback target). */
+export interface UpdateCommitResult {
+    readonly extensionId: string;
+    readonly activeVersion: string;
+    readonly previousVersion?: string;
+}
+/** The outcome of a rollback (pointer restore only). */
+export interface UpdateRollbackResult {
+    readonly extensionId: string;
+    readonly activeVersion: string;
+    readonly previousVersion?: string;
+    /**
+     * The rebindRestored hook's own failure, when it threw or rejected. The hook
+     * is a POST-RESTORE observer: its error is reported here, never thrown — the
+     * pointer restore has already committed and must not be rolled back again.
+     */
+    readonly hookFailure?: string;
+}
+/**
+ * Stage an update (EXT-30 slice 1).
+ *
+ * Fetch → integrity → entry validation → extract into `staging/` → manifest
+ * discovery → schema/licence/permission deltas against the current version →
+ * structural-static self-tests. A BREAKING schema delta or an unparseable
+ * schema REFUSES the stage (the staged directory is removed); a licence or
+ * permission delta only marks the stage as requiring approval. The installed
+ * version is never touched.
+ *
+ * @param options - the source, store, injected archive source, and limits.
+ * @returns the staged update and its validation report.
+ * @throws ManagementError for every rejection path.
+ */
+export declare function stageUpdate(options: {
+    readonly storeDir: string;
+    readonly source: InstallSource;
+    readonly archive: ArchiveSource;
+    readonly expectedSha512?: string;
+    /** The comparison base; defaults to the highest recorded version. */
+    readonly currentVersion?: string;
+    readonly limits?: InstallLimits;
+}): Promise<UpdateStageResult>;
+/**
+ * Record ONE operator approval decision for a staged update (EXT-30).
+ *
+ * The record is retained for the store's lifetime and is write-once per staged
+ * version (see {@link ExtensionStore.recordApproval}).
+ * @param options - the store, the staged identity, and the decision.
+ */
+export declare function recordApproval(options: {
+    readonly storeDir: string;
+    readonly extensionId: string;
+    readonly stagedVersion: string;
+    readonly decision: {
+        approved: true;
+    } | {
+        approved: false;
+        reason: string;
+    };
+}): void;
+/**
+ * Commit a staged, approved update (EXT-30, two-phase seam).
+ *
+ * Under the store lock, in order: verify the approval → verify the staged
+ * bytes (digest re-check, fail-closed) → verify the CURRENT active version's
+ * directory (fail-closed) → admit the staged version to its OWN version
+ * directory (never the live one) → **quiescePrevious** (the host stops
+ * old-generation admissions BEFORE the pointer moves; a failure aborts the
+ * commit with the pointer unchanged) → commit the pointer atomically via the
+ * profile-state writer → **rebindNext** (the host republishes the new
+ * generation; a failure rolls the pointer back AUTOMATICALLY and names the
+ * reason).
+ *
+ * REBIND-REVERT CONTRACT: the automatic rollback after a rebindNext failure
+ * runs NO further hooks — quiescePrevious is not re-run and no restore hook
+ * fires. A host whose rebind needs its own revert must supply it INSIDE its
+ * all-or-nothing rebindNext wrapper; the SDK never re-enters host hooks.
+ *
+ * NO-SEAM REFUSAL: a commit with no rebindNext REFUSES by default (the durable
+ * pointer must not advance while nothing republishes the surface). Pass
+ * `pointerOnly: true` as the explicit, documented deployment opt-out.
+ *
+ * @param options - the store, profile, staged identity, and the two-phase hooks.
+ * @returns the committed pointer and the previous one.
+ * @throws ManagementError for every rejection path.
+ */
+export declare function commitUpdate(options: {
+    readonly storeDir: string;
+    readonly profile: string;
+    readonly extensionId: string;
+    readonly stagedVersion: string;
+    /** Explicit opt-out: commit the pointer with NO hooks (deployment tooling only). */
+    readonly pointerOnly?: boolean;
+    readonly hooks?: {
+        /** Runs under the store lock BEFORE the pointer write; a failure aborts the commit. */
+        readonly quiescePrevious?: (previousVersion: string) => Promise<void>;
+        /** Runs AFTER the pointer write; a failure auto-rolls the pointer back. */
+        readonly rebindNext?: (stagedVersion: string) => Promise<void>;
+    };
+}): Promise<UpdateCommitResult>;
+/**
+ * Roll back one extension to its previous active version (EXT-30 slice 2).
+ *
+ * POINTER RESTORE ONLY: no bytes are copied over any live install, disabled
+ * tools stay disabled, revocations stay revoked (those facts live in the
+ * profile state beside the pointer). The previous version's directory is
+ * verified first; a corrupt previous version refuses the rollback (quarantine,
+ * the current pointer stays).
+ *
+ * The optional `rebindRestored` hook (the host's republish of the restored
+ * generation) runs AFTER the pointer restore. Its failure is REPORTED on the
+ * result as `hookFailure` — the restore stands and no second rollback runs.
+ *
+ * @param options - the store, profile, extension, and the optional restore hook.
+ * @returns the restored pointer.
+ */
+export declare function rollback(options: {
+    readonly storeDir: string;
+    readonly profile: string;
+    readonly extensionId: string;
+    /** Runs AFTER the pointer restore; a failure is reported, never rolled back again. */
+    readonly rebindRestored?: (restoredVersion: string) => Promise<void>;
+}): Promise<UpdateRollbackResult>;
+//# sourceMappingURL=update-flow.d.ts.map

package/node_modules/@try-works/tool-mode-extension-sdk/lib/install/update-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-flow.d.ts","sourceRoot":"","sources":["../../src/install/update-flow.ts"],"names":[],"mappings":"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"}