@hellraisercenobit/ai-engineering-gate 0.8.0

package/skills/engineering/transpose-modern-typescript/references/collections.md

@@ -0,0 +1,50 @@
+# Collections, memory and consumption
+
+## MT-06 - Match the collection to its operations
+
+**Intent/use:** choose object/Record for a known shape, Array for ordered positional data,
+Map for dynamic associations and Set for membership/uniqueness. Examine repeated scans
+that can share a maintained index.
+**Alternatives/trade-offs:** a one-shot small scan can be clearer and cheaper; index build
+and updates cost time and memory. Map/Set use SameValueZero and object identity; ordinary
+object keys coerce non-symbols to strings. Account for insertion order, duplicate policy
+(first/last/all), missing values and JSON boundaries.
+**Avoid:** claiming universal speed or guaranteed constant time; rebuilding an index per
+lookup; replacing a closed exhaustive typed table with an unchecked dynamic Map.
+**Invariants:** keys, duplicate/order policy, outputs and updates stay consistent. Average
+Map access is sublinear by specification, not a promise of a particular implementation.
+**Sources/support:** [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map),
+[Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set).
+Verify newer methods separately.
+
+## MT-07 - Match retention to ownership
+
+**Intent/use:** WeakMap/WeakSet suit metadata or membership tied to caller-owned object
+lifetimes when keys must not be retained solely by the association.
+**Alternatives/trade-offs:** Map/Set plus explicit deletion for enumeration, size, eviction
+or deterministic ownership. Bounded strong caches need expiry/eviction and invalidation.
+**Avoid:** enumerating weak collections, relying on collection timing, testing by forced GC,
+or claiming weak keys clean listeners/connections. Other strong references can retain keys.
+Weak-key types beyond objects require a separate compatibility check.
+**Invariants:** get/set/has/delete behavior is observable without GC; resource cleanup is
+explicit; no false enumeration, persistence or deterministic finalization guarantees.
+**Sources/support:** [WeakMap](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap),
+[WeakSet](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet).
+
+## MT-08 - Produce only what is consumed
+
+**Intent/use:** iterable/iterator protocols, function*, yield/yield* and async generators
+can avoid a full intermediate result when only a prefix is consumed. Use for await...of
+for asynchronous production; evaluate iterator helpers only where supported.
+**Alternatives/trade-offs:** arrays serve replay, random access and small bounded results.
+Generators defer side effects/errors and are usually consumed once per iterator. Streams
+add backpressure and cancellation semantics (MT-10).
+**Avoid:** making synchronous yield a UI-scheduling claim; hidden retained resources;
+changing iteration error timing without consent; materializing immediately without benefit.
+**Invariants:** counter shows no unrequested production; early break/return closes a
+started iterator and reaches appropriate finally cleanup; exhaustion/error/replay contract
+is explicit. A generator abandoned without close does not promise deterministic cleanup.
+**Sources/support:** [generators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*),
+[iteration protocols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols),
+[for await...of](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of).
+Check compiler downlevel iteration and runtime symbols/helpers separately.

package/skills/engineering/transpose-modern-typescript/references/compatibility.md

@@ -0,0 +1,61 @@
+# Compatibility and modules
+
+## MT-22 - Match emitted modules to their consumers
+
+**Intent/use:** import type for type-only dependencies where appropriate; explicit ESM/CJS
+and module resolution choices aligned with package consumers. Consider import defer only
+where compiler, emit, bundler and executing loader actually support its semantics.
+**Alternatives/trade-offs:** preserve deliberate side-effect imports, existing loaders or
+library distribution contracts. A compiler preset such as node20 describes specific module
+behavior, not a promise that any deployed Node supports every new API.
+**Avoid:** deleting runtime side effects by converting an import blindly, choosing a new
+TS option independently of the build chain, importing browser globals into server startup.
+**Invariants:** emitted entry points load on actual consumers; required effects still run;
+type-only boundaries and package exports are correct.
+**Sources/support:** [TS modules](https://www.typescriptlang.org/docs/handbook/modules/reference.html),
+[TS config](https://www.typescriptlang.org/tsconfig/),
+[import defer](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-9.html).
+Check current stable compiler documentation when adopting a newer feature.
+
+## MT-23 - Prove support across the deployment path
+
+**Intent/use:** every proposed idiom/API needs a project-specific support decision.
+Separate four layers: (1) parser/compiler syntax, (2) lib/type declarations, (3) emitted
+code and bundler/transforms, (4) actual runtime/platform. Passing tsc proves neither (3)
+nor (4). target/lib changes do not install runtime implementations.
+**Alternatives/trade-offs:** retain compatible code, use an existing library, or propose an
+explicitly costed polyfill/fallback when the user scope supports it. Do not silently raise
+targets or add polyfills.
+**Avoid:** a fixed TS minimum for all projects, a preview recommended as stable, npm version
+treated as market share, or browser support used as Node/Bun/Deno evidence.
+**Invariants:** identify exact supported targets and dated evidence for the feature; verify
+all required contexts (browser/worker/server/SSR), platform prerequisites and fallback paths.
+Unknown required targets remain an unresolved prerequisite for dependent adoption.
+
+## Build the profile
+
+Read the project lockfile and compiler command/version, tsconfig inheritance and relevant
+strictness, target/lib/module/moduleResolution, package engines/type/exports, bundler,
+Browserslist or equivalent product target policy, CI and deployment runtimes. Record
+unknowns explicitly. In a library, inspect consumer support, not just the maintainer machine.
+
+Sources of evidence: project files, runtime feature probes, official runtime release/API
+docs, TypeScript release/config docs, and MDN compatibility data for the exact feature.
+Record source, checked date, claim and targets covered. A single local browser probe only
+proves that browser/version, not the whole supported fleet.
+
+Baseline distinguishes newly available from widely available (30 months after interoperability
+in its browser set). A page saying a capability has existed across browsers since March
+2024 does not mean it was already Baseline widely available in March 2024. Object.groupBy
+and Promise.withResolvers are useful examples to re-check, not permanent universal support
+assertions. Baseline is not a substitute for actual product targets.
+
+Use stable modern features supported by the project. This repository's smoke compiler is
+locked for reproducibility and is not a language baseline imposed by the skills. Recheck
+stable releases and their actual toolchain support when upgrading the fixture dependency.
+
+**Sources:** [Baseline definition](https://web.dev/baseline),
+[MDN compatibility data](https://github.com/mdn/browser-compat-data),
+[TypeScript releases](https://www.typescriptlang.org/docs/handbook/release-notes/overview.html),
+[Node API documentation](https://nodejs.org/api/), [Bun](https://bun.sh/docs),
+[Deno](https://docs.deno.com/runtime/).

package/skills/engineering/transpose-modern-typescript/references/decision-envelope.schema.json

@@ -0,0 +1,215 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/hellraisercenobit/skills/blob/main/contracts/schemas/decision-envelope.schema.json",
+  "title": "Decision record envelope 1.0.0",
+  "description": "The outer shape every dimension's decision record shares. Enforcement validates a record against this envelope and against the dimension's own schema; the dimension-specific body stays opaque here. Applicability is not a record field: it lives in the declaration.",
+  "type": "object",
+  "required": [
+    "dimension",
+    "schemaVersion",
+    "catalogVersion",
+    "contractVersions",
+    "need",
+    "scope",
+    "base",
+    "revision",
+    "cites",
+    "plans"
+  ],
+  "properties": {
+    "dimension": {
+      "type": "string",
+      "minLength": 1
+    },
+    "schemaVersion": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "catalogVersion": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "contractVersions": {
+      "description": "The contract versions this record's member supports.",
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^\\d+\\.\\d+\\.\\d+$"
+      }
+    },
+    "need": {
+      "type": "string",
+      "minLength": 1
+    },
+    "scope": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "base": {
+      "type": "string",
+      "minLength": 1
+    },
+    "revision": {
+      "$ref": "#/$defs/revision"
+    },
+    "cites": {
+      "description": "Artifacts and evidence sources that exist when the record is validated. A dangling path refuses the record; every cited path is hashed with the revision.",
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/citation"
+      }
+    },
+    "plans": {
+      "description": "Artifacts the record commits to produce. Not checked when the record is written, so a record can precede the first affected write; required to exist before a review begins, is filed or is dispatched.",
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/plan"
+      }
+    }
+  },
+  "$defs": {
+    "citation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "path",
+        "checkedAt",
+        "claim",
+        "covers"
+      ],
+      "properties": {
+        "path": {
+          "description": "A repository-relative path, or a path under the task's evidence. Both are checked for existence.",
+          "type": "string",
+          "minLength": 1
+        },
+        "checkedAt": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+        },
+        "claim": {
+          "type": "string",
+          "minLength": 1
+        },
+        "covers": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "searched": {
+          "description": "Paths consulted and not found. Present when the citation supports a claim of unknown about a checkable fact.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "plan": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "path",
+        "role"
+      ],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "role": {
+          "description": "A role the dimension defines. Testing patterns uses `test` and `production` so a replay knows which files stand alone.",
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "revision": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "number",
+        "previous",
+        "reason"
+      ],
+      "properties": {
+        "number": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "previous": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "minLength": 1
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1
+        },
+        "changed": {
+          "description": "The cited paths this revision changed. Enforcement verifies their hashes differ from the previous revision's snapshot; absent, at least one cited path must differ.",
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "addresses": {
+          "description": "Finding identifiers this revision closes. A judgment finding is closed by a revision that cites it together with a moved state.",
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "number": {
+                "type": "integer",
+                "minimum": 2
+              }
+            },
+            "required": [
+              "number"
+            ]
+          },
+          "then": {
+            "properties": {
+              "previous": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "else": {
+            "properties": {
+              "previous": {
+                "type": "null"
+              }
+            }
+          }
+        }
+      ]
+    }
+  }
+}