feat(invariants): implement package runtime checks

packages/util/brand/src/invariant.ts

@@ -1,14 +1,8 @@
-/**
- * Generated invariant ownership companion for `@deepseek-ai/dsh-brand`.
- * Replace this file with package-owned checks while preserving its registration.
- *
- * @generated scripts/gen-package-invariants.ts
- * @module @deepseek-ai/dsh-brand/invariant
- */
+/** Package-owned runtime contract for @deepseek-ai/dsh-brand. @module @deepseek-ai/dsh-brand/invariant */
 
 /* jscpd:ignore-start */
 import type { Context } from 'cordis'
-import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import { assertInvariant, type InvariantInstaller } from '@deepseek-ai/dsh-invariants'
 
 const PACKAGE_NAME = '@deepseek-ai/dsh-brand'
 
@@ -17,8 +11,15 @@ export const name = 'brand-invariant'
 /** Services required before the companion can register. */
 export const inject = ['invariants']
 
-/** Reserve this package's invariant ownership until it adds relational checks. */
-const install: InvariantInstaller = () => {}
+/** Assert that the nominal-type primitive remains erased at runtime. */
+const install: InvariantInstaller = (ctx, fail) => {
+  ctx.effect(async () => {
+    const brandRuntime = await import('./index.ts')
+    assertInvariant(fail, Object.keys(brandRuntime).length === 0,
+      'the branded-id primitive must remain type-only with no runtime exports')
+    return () => {}
+  }, 'brand: validate type-only runtime erasure')
+}
 
 /**
  * Register this package's invariant companion.

packages/util/home/src/invariant.ts

@@ -1,14 +1,9 @@
-/**
- * Generated invariant ownership companion for `@deepseek-ai/dsh-home`.
- * Replace this file with package-owned checks while preserving its registration.
- *
- * @generated scripts/gen-package-invariants.ts
- * @module @deepseek-ai/dsh-home/invariant
- */
+/** Package-owned runtime contracts for @deepseek-ai/dsh-home. @module @deepseek-ai/dsh-home/invariant */
 
 /* jscpd:ignore-start */
+import { resolve } from 'node:path'
 import type { Context } from 'cordis'
-import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import { assertInvariant, type InvariantInstaller } from '@deepseek-ai/dsh-invariants'
 
 const PACKAGE_NAME = '@deepseek-ai/dsh-home'
 
@@ -17,8 +12,19 @@ export const name = 'home-invariant'
 /** Services required before the companion can register. */
 export const inject = ['invariants']
 
-/** Reserve this package's invariant ownership until it adds relational checks. */
-const install: InvariantInstaller = () => {}
+/** Assert the canonical environment key and configured-path precedence. */
+const install: InvariantInstaller = (ctx, fail) => {
+  ctx.effect(async () => {
+    const { DSH_HOME_ENV, resolveDshHome } = await import('./index.ts')
+    const environmentKey: string = DSH_HOME_ENV
+    assertInvariant(fail, environmentKey === ['DSH', 'HOME'].join('_'),
+      'the canonical Harness home environment key must remain DSH_HOME')
+    const configured = 'relative-invariant-home'
+    assertInvariant(fail, resolveDshHome(configured) === resolve(configured),
+      'an explicitly configured Harness home must normalize to an absolute path')
+    return () => {}
+  }, 'home: validate canonical DSH home resolution')
+}
 
 /**
  * Register this package's invariant companion.

packages/util/paths/src/invariant.ts

@@ -1,14 +1,10 @@
-/**
- * Generated invariant ownership companion for `@deepseek-ai/dsh-paths`.
- * Replace this file with package-owned checks while preserving its registration.
- *
- * @generated scripts/gen-package-invariants.ts
- * @module @deepseek-ai/dsh-paths/invariant
- */
+/** Package-owned runtime contracts for @deepseek-ai/dsh-paths. @module @deepseek-ai/dsh-paths/invariant */
 
 /* jscpd:ignore-start */
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
 import type { Context } from 'cordis'
-import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import { assertInvariant, type InvariantInstaller } from '@deepseek-ai/dsh-invariants'
 
 const PACKAGE_NAME = '@deepseek-ai/dsh-paths'
 
@@ -17,8 +13,19 @@ export const name = 'paths-invariant'
 /** Services required before the companion can register. */
 export const inject = ['invariants']
 
-/** Reserve this package's invariant ownership until it adds relational checks. */
-const install: InvariantInstaller = () => {}
+/** Assert tilde expansion and explicit-over-environment home precedence. */
+const install: InvariantInstaller = (ctx, fail) => {
+  ctx.effect(async () => {
+    const { DSH_HOME_ENV, expandHomePath, resolveDshHome } = await import('./index.ts')
+    assertInvariant(fail, expandHomePath('~/invariant-probe') === join(homedir(), 'invariant-probe'),
+      'supported tilde prefixes must expand against the operating-system home')
+    const configured = 'relative-invariant-home'
+    const resolved = resolveDshHome(configured, { [DSH_HOME_ENV]: '/ignored-environment-home' })
+    assertInvariant(fail, resolved === resolve(configured),
+      'an explicit DSH home must override the environment and normalize to an absolute path')
+    return () => {}
+  }, 'paths: validate DSH home resolution')
+}
 
 /**
  * Register this package's invariant companion.

packages/util/retention/src/invariant.ts

@@ -1,14 +1,8 @@
-/**
- * Generated invariant ownership companion for `@deepseek-ai/dsh-retention`.
- * Replace this file with package-owned checks while preserving its registration.
- *
- * @generated scripts/gen-package-invariants.ts
- * @module @deepseek-ai/dsh-retention/invariant
- */
+/** Package-owned runtime contracts for @deepseek-ai/dsh-retention. @module @deepseek-ai/dsh-retention/invariant */
 
 /* jscpd:ignore-start */
 import type { Context } from 'cordis'
-import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import { assertInvariant, type InvariantInstaller } from '@deepseek-ai/dsh-invariants'
 
 const PACKAGE_NAME = '@deepseek-ai/dsh-retention'
 
@@ -17,8 +11,26 @@ export const name = 'retention-invariant'
 /** Services required before the companion can register. */
 export const inject = ['invariants']
 
-/** Reserve this package's invariant ownership until it adds relational checks. */
-const install: InvariantInstaller = () => {}
+/** Assert exact head-retention accounting after the budget is exceeded. */
+const install: InvariantInstaller = (ctx, fail) => {
+  ctx.effect(async () => {
+    const { ItemRetainer } = await import('./index.ts')
+    const retainer = new ItemRetainer<string>({ kind: 'head', maxItems: 2 })
+    retainer.push('first')
+    retainer.push('second')
+    retainer.push('third')
+    const result = retainer.finish()
+    assertInvariant(fail,
+      result.items.join(',') === 'first,second'
+        && result.seen === 3
+        && result.kept === 2
+        && result.truncated
+        && result.omitted.kind === 'exact'
+        && result.omitted.count === 1,
+      'head retention must keep the prefix and report exact seen, kept, and omitted counts')
+    return () => {}
+  }, 'retention: validate exact head accounting')
+}
 
 /**
  * Register this package's invariant companion.

packages/util/timeout/src/invariant.ts

@@ -1,14 +1,8 @@
-/**
- * Generated invariant ownership companion for `@deepseek-ai/dsh-timeout`.
- * Replace this file with package-owned checks while preserving its registration.
- *
- * @generated scripts/gen-package-invariants.ts
- * @module @deepseek-ai/dsh-timeout/invariant
- */
+/** Package-owned runtime contracts for @deepseek-ai/dsh-timeout. @module @deepseek-ai/dsh-timeout/invariant */
 
 /* jscpd:ignore-start */
 import type { Context } from 'cordis'
-import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import { assertInvariant, type InvariantInstaller } from '@deepseek-ai/dsh-invariants'
 
 const PACKAGE_NAME = '@deepseek-ai/dsh-timeout'
 
@@ -17,8 +11,21 @@ export const name = 'timeout-invariant'
 /** Services required before the companion can register. */
 export const inject = ['invariants']
 
-/** Reserve this package's invariant ownership until it adds relational checks. */
-const install: InvariantInstaller = () => {}
+/** Assert default-before-cap arithmetic and capability-code classification. */
+const install: InvariantInstaller = (ctx, fail) => {
+  ctx.effect(async () => {
+    const { clampTimeout, TimeoutReason, timeoutOf } = await import('./index.ts')
+    assertInvariant(fail,
+      clampTimeout(undefined, 50, 30) === 30 && clampTimeout(20, 50, 30) === 20,
+      'timeout resolution must apply the default before capping and preserve smaller requests')
+    const reason = new TimeoutReason('INVARIANT_TIMEOUT', 25)
+    assertInvariant(fail, timeoutOf({ reason }, 'INVARIANT_TIMEOUT') === reason,
+      'timeout classification must recover a matching capability-owned reason')
+    assertInvariant(fail, timeoutOf({ reason }, 'FOREIGN_TIMEOUT') === undefined,
+      'timeout classification must reject a reason owned by another capability')
+    return () => {}
+  }, 'timeout: validate resolution and reason classification')
+}
 
 /**
  * Register this package's invariant companion.