From 1fb58b82a5ee2df54cd79f30d61838177f52abeb Mon Sep 17 00:00:00 2001 From: Okiki Ojo Date: Thu, 23 Jul 2026 22:49:02 -0400 Subject: [PATCH] feat: add selective adoption and streaming cleanup fixtures - Introduced selective adoption fixture with README and package.json to ensure core facade exposure without browser adapter import. - Implemented core functionality in core.mjs and browser adapter in browser.mjs, ensuring no global state mutation. - Created verification script to validate selective adoption behavior and module exports. - Added streaming cleanup fixture with README and collect.mjs to implement lazy resource acquisition and async iterable return. - Developed verification script for streaming cleanup to ensure proper resource management and disposal. - Updated sources.json with new references related to library design and resource management. - Created build-libraries initialization report detailing the scope, accepted skill surface, ecosystem position, and verification processes. Signed-off-by: Okiki Ojo --- evals/README.md | 7 + evals/capabilities.json | 254 +++ evals/cases/library-design-deep.json | 1747 +++++++++++++++++ .../library-selective-adoption/README.md | 5 + .../library-selective-adoption/package.json | 8 + .../src/browser.mjs | 5 + .../library-selective-adoption/src/core.mjs | 3 + .../library-selective-adoption/src/index.mjs | 2 + .../library-selective-adoption/verify.mjs | 51 + .../library-streaming-cleanup/README.md | 5 + .../library-streaming-cleanup/src/collect.mjs | 9 + .../library-streaming-cleanup/verify.mjs | 54 + evals/sources.json | 74 + reports/build-libraries-initialization.md | 172 ++ 14 files changed, 2396 insertions(+) create mode 100644 evals/cases/library-design-deep.json create mode 100644 evals/fixtures/library-selective-adoption/README.md create mode 100644 evals/fixtures/library-selective-adoption/package.json create mode 100644 evals/fixtures/library-selective-adoption/src/browser.mjs create mode 100644 evals/fixtures/library-selective-adoption/src/core.mjs create mode 100644 evals/fixtures/library-selective-adoption/src/index.mjs create mode 100644 evals/fixtures/library-selective-adoption/verify.mjs create mode 100644 evals/fixtures/library-streaming-cleanup/README.md create mode 100644 evals/fixtures/library-streaming-cleanup/src/collect.mjs create mode 100644 evals/fixtures/library-streaming-cleanup/verify.mjs create mode 100644 reports/build-libraries-initialization.md diff --git a/evals/README.md b/evals/README.md index 610bd8b..8fdfd1f 100644 --- a/evals/README.md +++ b/evals/README.md @@ -57,6 +57,13 @@ still require a rollout and judge runner; they are not executable outcomes. Release claims must use real trajectories and executable cases, not the smoke corpus or raw case totals. +`library-design-deep.json` covers use-case-first architecture, multi-scale +ecosystem composition, truthful data-flow contracts, data-oriented internals, +explicit resource ownership, workload-specific performance, selective package +graphs, recovery, refactoring, and claim-to-evidence verification. Its frozen +fixtures exercise selective adoption and import-time effects, plus lazy async +iteration, early termination, failure cleanup, and deterministic disposal. + `evidence.json` contains source-grounded cases from the attached guidebooks and repositories. Its fixture cases cover Markdown preservation, CLI task parity, single configuration evaluation, result redaction, native site semantics, diff --git a/evals/capabilities.json b/evals/capabilities.json index 3c7611b..e235e95 100644 --- a/evals/capabilities.json +++ b/evals/capabilities.json @@ -1961,6 +1961,260 @@ "verification": [ "Run behavior-specific tests or subprocess commands for parser sparsity, merge/provenance, result isolation, stage/artifact validation, source run behavior, lifecycle cleanup, generated surfaces, and installed artifact reachability." ] + }, + { + "id": "cap-library-architecture", + "skill": "build-libraries", + "reference": "references/architecture.md", + "capability": "Use-case-first library architecture and deep public modules", + "ownership": "The library skill owns consumer-shaped public APIs, information-hiding boundaries, deep common-case facades, focused lower-level capabilities, and the separation between reusable code and application shells.", + "status": "normative", + "sourceIds": [ + "library-first-guidebook", + "semver-official", + "decision-justification-guide" + ], + "evalIds": [ + "library-architecture-use-case-first", + "library-architecture-deep-module", + "library-architecture-framework-exception", + "library-architecture-justify-boundary" + ], + "decisionQuestions": [ + "Which concrete consumers and use cases define the public programming model, which decisions must each module hide, and when is a framework-style extension protocol genuinely the product?" + ], + "failureSignatures": [ + "The package preserves a CLI flowchart, requires a universal runtime or context, exposes many shallow wrappers, or rejects every valid plugin framework without examining the extension requirement." + ], + "exclusions": [ + "Do not treat moving files into a package as library design, equate export count with flexibility, or ban stages and plugins when third-party lifecycle extension is an explicit product capability." + ], + "verification": [ + "Exercise representative common and advanced consumer call sites, inspect public exports and compatibility commitments, and verify the application shell owns argv, configuration discovery, rendering, signals, and process exits." + ] + }, + { + "id": "cap-library-composition", + "skill": "build-libraries", + "reference": "references/composition.md", + "capability": "Multi-scale library and ecosystem composition", + "ownership": "The library skill owns composition across values, data flow, capabilities, policies, ecosystems, lifecycles, package graphs, and operations while preserving the semantics and ownership boundaries of strategic dependencies.", + "status": "normative", + "sourceIds": [ + "library-first-guidebook", + "logtape-official", + "c12-official", + "defu-official", + "unstorage-1-17-5", + "hookable-6-1-1" + ], + "evalIds": [ + "library-composition-multiscale", + "library-composition-strategic-dependency", + "library-composition-no-ecosystem-hoarding" + ], + "decisionQuestions": [ + "At which composition scales must the library cooperate, which ecosystem dependency should be used directly or adapted, and which owner configures logging, resolves configuration, chooses storage guarantees, and governs extensions?" + ], + "failureSignatures": [ + "A lowest-common-denominator interface erases LogTape, c12, defu, or unstorage semantics; the library configures host-wide systems; or an umbrella package eagerly imports an ecosystem that consumers did not select." + ], + "exclusions": [ + "Do not confuse swappability with composability, wrap strategic dependencies merely to hide their names, or add Hookable and plugin machinery when ordinary functions satisfy all known consumers." + ], + "verification": [ + "Trace one owner per ecosystem boundary, test domain events separately from diagnostics, validate application-owned configuration resolution, and inspect installed dependency and entrypoint reachability for optional integrations." + ] + }, + { + "id": "cap-library-data-flow", + "skill": "build-libraries", + "reference": "references/data-flow.md", + "capability": "Truthful cardinality, streaming, batching, and backpressure contracts", + "ownership": "The library skill owns the choice and semantics of values, arrays, iterables, generators, async iterables, streams, explicit batches, materialization points, early termination, cancellation, and bounded producer-consumer flow.", + "status": "normative", + "sourceIds": [ + "library-first-guidebook", + "whatwg-streams-standard", + "typescript-erm-official" + ], + "evalIds": [ + "library-data-flow-shape-selection", + "library-data-flow-batching", + "library-data-flow-streaming-cleanup-fixture", + "library-data-flow-cancellation-boundary" + ], + "decisionQuestions": [ + "Is the result singular or plural, bounded or incremental, reusable or one-shot, pull-oriented or backpressured, and where should batching or explicit materialization occur?" + ], + "failureSignatures": [ + "A Promise of a giant array hides incremental work, an async iterable buffers unboundedly, a one-record pipeline pays excessive protocol overhead, or breaking consumption leaves upstream work and resources alive." + ], + "exclusions": [ + "Do not expose a universal union of arrays, iterables, async iterables, and streams that pushes semantic decisions to every caller, and do not call an implementation streaming merely because its return type is AsyncIterable." + ], + "verification": [ + "Assert laziness, first-result latency, bounded buffers, batch limits, early return, cancellation, upstream stop behavior, disposal, error propagation, and explicit array materialization in executable fixtures." + ] + }, + { + "id": "cap-library-data-oriented-design", + "skill": "build-libraries", + "reference": "references/data-oriented-design.md", + "capability": "Transform-first data-oriented library internals", + "ownership": "The library skill owns workload-grounded transform graphs, data volume and lifetime analysis, hot and cold field separation, indexing, allocation and locality decisions, and intentional boundaries between ergonomic public values and optimized internal representations.", + "status": "normative", + "sourceIds": [ + "library-first-guidebook", + "data-oriented-design-book", + "v8-performance-official" + ], + "evalIds": [ + "library-dod-transform-graph", + "library-dod-hot-cold-index", + "library-dod-typed-array-cargo-cult" + ], + "decisionQuestions": [ + "What transforms dominate the workload, which fields are accessed together, what volumes and lifetimes exist, and which representation improves measured CPU, memory, locality, or allocation without corrupting the public model?" + ], + "failureSignatures": [ + "The design begins from object taxonomies rather than transforms, scans cold metadata on hot paths, allocates per-record wrappers excessively, or replaces clear objects with typed arrays without a measured bottleneck." + ], + "exclusions": [ + "Do not confuse data-oriented design with declarative data-driven policy, use typed arrays as an aesthetic default, or expose packed internal layouts as the public API without a compatibility reason." + ], + "verification": [ + "Benchmark representative transforms with correctness oracles, allocation and memory evidence, compare baseline and optimized representations, and retain conversion boundaries between public records and hot internal batches." + ] + }, + { + "id": "cap-library-resources-performance", + "skill": "build-libraries", + "reference": "references/resources-performance.md", + "capability": "Explicit resource ownership and workload-specific performance budgets", + "ownership": "The library skill owns acquisition, borrowing, transfer, cancellation, deterministic disposal, partial-construction cleanup, bounded concurrency and buffering, and measurable CPU, memory, latency, startup, resource, cleanup, and recovery budgets.", + "status": "normative", + "sourceIds": [ + "library-first-guidebook", + "typescript-erm-official", + "v8-performance-official", + "logtape-official" + ], + "evalIds": [ + "library-resources-ownership", + "library-performance-budget", + "library-resource-early-return" + ], + "decisionQuestions": [ + "Who owns each resource, how does every success, failure, cancellation, and early-return path release it, and which workload dimensions and thresholds define acceptable performance?" + ], + "failureSignatures": [ + "Resources leak on partial failure or early termination, cancellation is mistaken for disposal, concurrency or buffers are unbounded, or a benchmark reports only average time while ignoring correctness, memory, variance, and resource counts." + ], + "exclusions": [ + "Do not require explicit resource management syntax where the target runtime cannot support it; preserve the ownership contract with try/finally, and do not optimize one metric while silently violating another budget." + ], + "verification": [ + "Run lifecycle fixtures across success, failure, cancellation, and early return; measure cold and warm latency, throughput, tail latency, CPU, peak and retained memory, allocations, open resources, cleanup time, and representative recovery cost." + ] + }, + { + "id": "cap-library-packaging", + "skill": "build-libraries", + "reference": "references/packaging.md", + "capability": "Selective ESM packaging and tree-shakable public entrypoints", + "ownership": "The library skill owns public exports and subpaths, ESM-preserving output, truthful side-effect metadata, optional adapter isolation, declaration reachability, and clean-consumer proof that unused capabilities and dependencies are absent.", + "status": "normative", + "sourceIds": [ + "library-first-guidebook", + "node-packages-official", + "esbuild-tree-shaking-official", + "semver-official" + ], + "evalIds": [ + "library-packaging-subpaths", + "library-packaging-side-effects", + "library-packaging-selective-fixture", + "library-packaging-runtime-registry-trap" + ], + "decisionQuestions": [ + "Which entrypoints are public compatibility surfaces, which modules have import-time effects, and can a clean consumer select the core without retaining optional adapters or their dependency subtrees?" + ], + "failureSignatures": [ + "The root barrel eagerly imports every adapter, sideEffects metadata lies, build output collapses all features into one mandatory graph, declarations expose private paths, or source inspection substitutes for bundled-consumer evidence." + ], + "exclusions": [ + "Do not set sideEffects to false without auditing import-time behavior, expose internal files with wildcards by default, or claim tree-shaking from named exports alone." + ], + "verification": [ + "Install the packed artifact into clean consumers, import root and explicit subpaths, run type checks, inspect bundler metafiles and output graphs, assert no import-time mutation, and compare bundle contents with and without optional integrations." + ] + }, + { + "id": "cap-library-recovery-refactoring", + "skill": "build-libraries", + "reference": "references/recovery-refactoring.md", + "capability": "Precise recovery contracts and CLI-first library extraction", + "ownership": "The library skill owns restartable and checkpoint-resumable operation contracts, commit ordering, compatibility fingerprints, idempotent replay boundaries, and phased extraction from application-shaped workflows while durable execution authority remains with build-workflows.", + "status": "normative", + "sourceIds": [ + "library-first-guidebook", + "unstorage-1-17-5", + "ohash-2-0-11", + "temporal-typescript-official", + "cli-guidebook", + "cli-audit" + ], + "evalIds": [ + "library-recovery-ladder", + "library-recovery-commit-order", + "library-refactor-cli-first" + ], + "decisionQuestions": [ + "Is the operation merely restartable, checkpoint-resumable, or durably orchestrated; what output becomes authoritative before a checkpoint advances; and how can a CLI-shaped codebase gain a second programmatic consumer without a speculative rewrite?" + ], + "failureSignatures": [ + "An iterator index is called a durable checkpoint, checkpoint state advances before output durability, incompatible requests resume silently, or a big-bang refactor preserves the shared runtime under new names without proving a second consumer." + ], + "exclusions": [ + "Do not claim durable orchestration without persisted execution authority and reachable workers, and do not rewrite every package before characterizing one representative command and extracting one use-case boundary." + ], + "verification": [ + "Test crash windows around output and checkpoint commits, replay and duplicate handling, fingerprint incompatibility, startup reconciliation, CLI subprocess parity, direct programmatic consumption, and removal of obsolete compatibility surfaces." + ] + }, + { + "id": "cap-library-verification", + "skill": "build-libraries", + "reference": "references/verification.md", + "capability": "Evidence-backed library verification across source, artifact, runtime, and workload layers", + "ownership": "The library skill owns the claim-to-evidence matrix for public APIs, built artifacts, clean consumers, streaming and lifecycle semantics, performance budgets, recovery guarantees, compatibility, and cross-skill release composition.", + "status": "normative", + "sourceIds": [ + "library-first-guidebook", + "node-packages-official", + "esbuild-tree-shaking-official", + "typescript-erm-official", + "whatwg-streams-standard", + "deno-software" + ], + "evalIds": [ + "library-verification-claim-evidence", + "library-verification-benchmark-gate", + "library-verification-cross-skill" + ], + "decisionQuestions": [ + "What observable artifact or executable scenario proves each library claim, which checks belong to adjacent skills, and which blocked checks must remain explicitly unverified?" + ], + "failureSignatures": [ + "Source code is treated as proof of package behavior, unit tests stand in for clean-consumer or subprocess evidence, performance claims omit workload and variability, or a release verdict silently assumes blocked model, platform, or recovery checks passed." + ], + "exclusions": [ + "Do not duplicate CLI, workflow, data, or developer-tool ownership; compose their evidence into one release verdict, and do not mark unavailable external model rollouts or platform tests as successful." + ], + "verification": [ + "Maintain deterministic fixtures, rubric and held-out evals, packed-artifact consumers, package graph inspection, lifecycle and recovery fault injection, benchmark baselines and thresholds, cross-skill composition cases, and an honest pass, fail, blocked report." + ] } ] } diff --git a/evals/cases/library-design-deep.json b/evals/cases/library-design-deep.json new file mode 100644 index 0000000..c59e88b --- /dev/null +++ b/evals/cases/library-design-deep.json @@ -0,0 +1,1747 @@ +{ + "schemaVersion": 2, + "cases": [ + { + "id": "library-architecture-use-case-first", + "title": "Derive a library from consumer use cases", + "skill": "build-libraries", + "kind": "trajectory", + "split": "train", + "prompt": "A CLI has parse, configure, acquire, collect, verify, detect, export, and upload stages plus a shared RuntimeContext. Design the reusable library API without preserving the CLI flowchart as its module structure. Show common and advanced consumer call sites, request/result/failure/event contracts, and the application boundary.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/architecture.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "use.?case|consumer call" + }, + { + "kind": "regex", + "value": "request.*result.*fail.*event" + }, + { + "kind": "regex", + "value": "CLI.*(adapter|composition root)|application.*owner" + }, + { + "kind": "not-contains", + "value": "Stage" + } + ], + "rubric": [ + "Begins from concrete consumers and domain language", + "Keeps CLI and process concerns outside the reusable core", + "Provides a deep facade plus independently useful capabilities" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "architecture", + "training" + ], + "rationale": "The optimizer needs the central use-case-first correction." + }, + { + "id": "library-architecture-deep-module", + "title": "Prefer deep modules over shallow wrappers", + "skill": "build-libraries", + "kind": "knowledge", + "split": "valid-seen", + "prompt": "Review a proposed SDK with 42 public classes, each wrapping one HTTP call, plus a universal Runtime object required by every method. Explain what should remain public, what knowledge each module should hide, and how to preserve a convenient facade without forcing the runtime on all consumers.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/architecture.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "deep module|small.*surface|information hid" + }, + { + "kind": "regex", + "value": "facade|common case" + }, + { + "kind": "regex", + "value": "focused capabilit|narrow.*contract" + }, + { + "kind": "regex", + "value": "public.*compatib|version" + } + ], + "rubric": [ + "Rejects surface-area-as-composability", + "Identifies change axes and hidden knowledge", + "Treats exports as compatibility commitments" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "semver-official" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "architecture", + "valid-seen" + ], + "rationale": "Library quality depends on depth and ownership, not class count." + }, + { + "id": "library-architecture-framework-exception", + "title": "Recognize when a framework is the library", + "skill": "build-libraries", + "kind": "knowledge", + "split": "adversarial", + "prompt": "A compiler toolkit lets third parties define passes, order them, inspect lifecycle events, and publish plugins. A reviewer says all Stage and Plugin abstractions are always wrong and must become plain functions. Decide whether the framework shape is justified and specify the contracts it must expose and verify.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/architecture.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "framework.*product|third.party extension" + }, + { + "kind": "regex", + "value": "order|lifecycle|compatib|failure" + }, + { + "kind": "regex", + "value": "plain function.*not|not.*always" + } + ], + "rubric": [ + "Does not turn the guidance into a ban on frameworks", + "Requires evidence that extension is the product", + "Defines lifecycle and compatibility obligations" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "architecture", + "adversarial" + ], + "rationale": "The skill must preserve valid framework use cases." + }, + { + "id": "library-composition-multiscale", + "title": "Map composition beyond function pipelines", + "skill": "build-libraries", + "kind": "trajectory", + "split": "train", + "prompt": "Design a library that uses LogTape diagnostics, receives c12-resolved configuration, stores optional checkpoints through unstorage, and offers a Hookable plugin surface. Map value, data-flow, capability, policy, ecosystem, lifecycle, package, and operational composition, with one owner per boundary.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/composition.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "value.*data.?flow.*capabilit|ecosystem.*lifecycle" + }, + { + "kind": "regex", + "value": "LogTape.*(not|does not).*configure|application.*configure" + }, + { + "kind": "regex", + "value": "c12.*application|resolved.*value" + }, + { + "kind": "regex", + "value": "unstorage.*guarantee|driver" + }, + { + "kind": "regex", + "value": "Hookable.*third.party|extension.*requirement" + } + ], + "rubric": [ + "Covers all composition scales", + "Preserves each ecosystem's semantics and owner", + "Does not equate common interfaces with common guarantees" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "logtape-official", + "c12-official", + "unstorage-1-17-5", + "hookable-6-1-1" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "composition", + "training" + ], + "rationale": "Local function composition alone misses ecosystem and operational contracts." + }, + { + "id": "library-composition-strategic-dependency", + "title": "Choose direct dependency or project adapter", + "skill": "build-libraries", + "kind": "knowledge", + "split": "valid-seen", + "prompt": "A library wants logging. One proposal imports LogTape directly with a namespaced category and leaves configuration to the host. Another wraps it as Logger.log(string). Compare the options, state when a project-owned adapter is warranted, and preserve domain events separately from diagnostics.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/composition.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "strategic depend|direct.*LogTape" + }, + { + "kind": "regex", + "value": "structured|category|context|redact|lazy" + }, + { + "kind": "regex", + "value": "domain event.*diagnostic|diagnostic.*domain event" + }, + { + "kind": "regex", + "value": "adapter.*semantics|substitut" + } + ], + "rubric": [ + "Rejects the lowest-common-denominator wrapper", + "Explains when an adapter is justified", + "Separates stable domain events from support diagnostics" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "logtape-official" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "composition", + "logtape", + "valid-seen" + ], + "rationale": "Swappability must not erase strategic ecosystem value." + }, + { + "id": "library-composition-no-ecosystem-hoarding", + "title": "Select the smallest coherent ecosystem set", + "skill": "build-libraries", + "kind": "trajectory", + "split": "valid-unseen", + "prompt": "An SDK already uses LogTape, c12, defu, and unstorage. A proposal adds Consola, a second config loader, a second merge library, and an internal event bus because they are all composable. Produce the ownership and exclusion decision, including where Hookable would actually be justified.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/composition.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "duplicate|overlap|one owner" + }, + { + "kind": "regex", + "value": "Consola.*alternative|second.*logger" + }, + { + "kind": "regex", + "value": "Hookable.*third.party|plugin" + }, + { + "kind": "regex", + "value": "smallest coherent|exclude" + } + ], + "rubric": [ + "Does not maximize package count", + "Distinguishes companions from alternatives", + "Requires a real extension contract before adding hooks" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "cli-audit", + "hookable-6-1-1" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "composition", + "ecosystems", + "valid-unseen" + ], + "rationale": "Composability is not ecosystem accumulation." + }, + { + "id": "library-data-flow-shape-selection", + "title": "Choose truthful collection and stream shapes", + "skill": "build-libraries", + "kind": "knowledge", + "split": "train", + "prompt": "For each operation choose and justify T, Promise, readonly T[], Iterable, AsyncIterable, ReadableStream, or AsyncIterable: compile 500 rules, crawl 100,000 domains, decode a response body, return a final summary, and batch database writes.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/data-flow.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "rules.*array|readonly" + }, + { + "kind": "regex", + "value": "domains.*AsyncIterable|crawl.*AsyncIterable" + }, + { + "kind": "regex", + "value": "response.*ReadableStream|bytes.*stream" + }, + { + "kind": "regex", + "value": "batch|materiali" + } + ], + "rubric": [ + "Matches shape to cardinality and semantics", + "Uses arrays as explicit materialization boundaries", + "Distinguishes domain async iteration from transport streams" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "whatwg-streams-standard" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "data-flow", + "training" + ], + "rationale": "The data shape is part of the public contract." + }, + { + "id": "library-data-flow-batching", + "title": "Stream between subsystems and batch within them", + "skill": "build-libraries", + "kind": "trajectory", + "split": "valid-seen", + "prompt": "A domain pipeline yields one Observation at a time, awaits one database insert per record, logs every record, and preserves input order across skewed network requests. Redesign it with bounded admission, concurrency, buffering, ordering policy, byte/count/time batch limits, and explicit materialization points.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/data-flow.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "admission.*concurrency.*buffer|queue capacity" + }, + { + "kind": "regex", + "value": "batch.*(bytes|count|time)" + }, + { + "kind": "regex", + "value": "input.*completion.*order|ordering policy" + }, + { + "kind": "regex", + "value": "backpressure|slow.*sink" + } + ], + "rubric": [ + "Separates admission, concurrency, buffering, and ordering", + "Batches hot subsystem work without destroying incremental flow", + "Accounts for slow destinations and gap buffering" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "whatwg-streams-standard" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "data-flow", + "batching", + "valid-seen" + ], + "rationale": "Per-record elegance can hide serious CPU, I/O, and memory overhead." + }, + { + "id": "library-data-flow-streaming-cleanup-fixture", + "title": "Repair lazy streaming and early-return cleanup", + "skill": "build-libraries", + "kind": "artifact", + "split": "test-frozen", + "prompt": "Repair collectItems() so it is a lazy AsyncIterable, reads one item at a time, stops upstream work when the consumer breaks, disposes the acquired AsyncDisposable exactly once on early return and failure, and passes the fixture verifier. Use explicit resource management where the target runtime supports it, otherwise preserve the same contract with try/finally.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/data-flow.md" + ], + "assertions": [ + { + "kind": "command", + "command": [ + "node", + "verify.mjs" + ], + "expectedExitCode": 0 + } + ], + "rubric": [ + "Returns an async iterable rather than a materialized promise", + "Acquires lazily and stops after early return", + "Disposes on normal early return and source failure" + ], + "oracleStrength": "fixture-behavior", + "sourceIds": [ + "library-first-guidebook", + "whatwg-streams-standard", + "typescript-erm-official" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "data-flow", + "streaming", + "frozen" + ], + "rationale": "Executable proof protects incrementality and cleanup semantics.", + "fixture": "library-streaming-cleanup" + }, + { + "id": "library-dod-transform-graph", + "title": "Design from transformations and data lifetime", + "skill": "build-libraries", + "kind": "trajectory", + "split": "train", + "prompt": "A technology detection library processes millions of observations. Produce a data-oriented design from target normalization through observation batches, detector index probes, fact candidates, aggregation, and persistence. Record cardinality, fields accessed, allocation, copying, lifetime, batching, and public versus internal representations.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/data-oriented-design.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "transform.*graph|cardinalit" + }, + { + "kind": "regex", + "value": "hot.*cold|lifetime" + }, + { + "kind": "regex", + "value": "public.*internal.*represent|internal.*public" + }, + { + "kind": "regex", + "value": "allocation|copy|locality" + } + ], + "rubric": [ + "Uses the transformation graph rather than object taxonomy", + "Separates stable public models from optimized internal batches", + "Accounts for volume, lifetime, allocation, and access patterns" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "data-oriented-design-book", + "v8-performance-official" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "data-oriented-design", + "training" + ], + "rationale": "Data-oriented design begins with data and transforms." + }, + { + "id": "library-dod-hot-cold-index", + "title": "Separate hot records cold evidence and indexes", + "skill": "build-libraries", + "kind": "knowledge", + "split": "valid-seen", + "prompt": "Each fact candidate currently embeds a large evidence object and string technology name. The hot loop repeatedly groups and scores millions of candidates. Propose a measured internal representation, evidence store, identifiers, index lifetime, and conversion boundary while keeping the public API readable.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/data-oriented-design.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "hot.*cold|evidence store" + }, + { + "kind": "regex", + "value": "ID|identifier|dictionary|index" + }, + { + "kind": "regex", + "value": "public.*boundary|conversion" + }, + { + "kind": "regex", + "value": "measure|benchmark|profile" + } + ], + "rubric": [ + "Reduces hot-path payload without leaking packed internals", + "Includes index build, memory, invalidation, and lifetime costs", + "Requires end-to-end evidence" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "data-oriented-design-book", + "v8-performance-official" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "data-oriented-design", + "valid-seen" + ], + "rationale": "Hot and cold separation is useful only with explicit conversion and lifetime costs." + }, + { + "id": "library-dod-typed-array-cargo-cult", + "title": "Reject unmeasured typed-array redesign", + "skill": "build-libraries", + "kind": "knowledge", + "split": "adversarial", + "prompt": "A 200-rule configuration library runs once at startup. A reviewer demands struct-of-arrays, numeric IDs, object pooling, and typed arrays because data-oriented design is always faster. Evaluate the proposal, define the evidence that could justify it, and choose the default representation now.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/data-oriented-design.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "premature|cargo|not.*typed array|ordinary object" + }, + { + "kind": "regex", + "value": "small|startup|200" + }, + { + "kind": "regex", + "value": "profile|benchmark|threshold" + }, + { + "kind": "regex", + "value": "conversion|complexity" + } + ], + "rubric": [ + "Does not equate data-oriented design with typed arrays", + "Chooses understandable bounded data by default", + "Defines conditions that would justify revisiting the representation" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "data-oriented-design-book" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "data-oriented-design", + "adversarial" + ], + "rationale": "The skill must prevent representation cargo culting." + }, + { + "id": "library-resources-ownership", + "title": "Model resource acquisition borrowing and disposal", + "skill": "build-libraries", + "kind": "trajectory", + "split": "train", + "prompt": "Design a library API that uses a shared browser pool, per-run temporary workspace, per-target browser context, database transaction, stream writer, and checkpoint session. Define owner, lifetime, borrow/transfer policy, cancellation, partial-construction cleanup, disposal order, and supported using/await using fallback.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/resources-performance.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "application.*run.*target|lifetime" + }, + { + "kind": "regex", + "value": "borrow|transfer" + }, + { + "kind": "regex", + "value": "AsyncDisposable|await using|try/finally" + }, + { + "kind": "regex", + "value": "partial.*construct|reverse.*order" + } + ], + "rubric": [ + "Separates resources by lifetime", + "Makes ownership transfer and cleanup explicit", + "Handles partial failure, abort, and cleanup failure" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "typescript-erm-official" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "resources", + "training" + ], + "rationale": "Resource lifetime is a public API concern." + }, + { + "id": "library-performance-budget", + "title": "Define multidimensional workload budgets", + "skill": "build-libraries", + "kind": "trajectory", + "split": "valid-seen", + "prompt": "A browser-analysis library claims it is faster after raising concurrency from 8 to 64. Design a performance evaluation that covers startup, first result, throughput, p95/p99, CPU, allocation, peak and retained memory, queue depth, open browsers/pages, cleanup, and recovery under fixed admission and destination behavior.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/resources-performance.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "startup|first.*result" + }, + { + "kind": "regex", + "value": "p95|p99|tail" + }, + { + "kind": "regex", + "value": "peak.*retained|allocation|RSS" + }, + { + "kind": "regex", + "value": "admission.*queue|buffer" + }, + { + "kind": "regex", + "value": "baseline|variab|oracle" + } + ], + "rubric": [ + "Rejects throughput achieved through unbounded queue growth", + "Separates CPU, memory, latency, resource, and cleanup metrics", + "Defines representative baseline and correctness gates" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "v8-performance-official" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "performance", + "valid-seen" + ], + "rationale": "Performance is workload-specific and multidimensional." + }, + { + "id": "library-resource-early-return", + "title": "Prove cancellation and cleanup are separate", + "skill": "build-libraries", + "kind": "knowledge", + "split": "valid-unseen", + "prompt": "An async iterable accepts AbortSignal and calls abort() when the consumer stops, but leased pages, a reader lock, and a temporary directory remain open until process exit. Explain the defect and design the lifecycle and tests for normal completion, early return, source error, consumer error, and cleanup failure.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/resources-performance.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "AbortSignal.*(not|does not).*dispose|cancellation.*disposal" + }, + { + "kind": "regex", + "value": "early return|consumer error|source error" + }, + { + "kind": "regex", + "value": "reader.*lock|page|temporary" + }, + { + "kind": "regex", + "value": "exactly once|cleanup.*failure" + } + ], + "rubric": [ + "Distinguishes stop requests from resource release", + "Covers all lifecycle exits", + "Preserves primary and cleanup failure evidence" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "typescript-erm-official", + "whatwg-streams-standard" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "resources", + "cancellation", + "valid-unseen" + ], + "rationale": "Abort propagation alone is not resource safety." + }, + { + "id": "library-packaging-subpaths", + "title": "Design ESM public subpaths and optional adapters", + "skill": "build-libraries", + "kind": "trajectory", + "split": "train", + "prompt": "Design package.json exports and source boundaries for a core analysis library plus browser, PostgreSQL, ClickHouse, LogTape, and Temporal adapters. Preserve ESM, explicit extensions, declarations, optional dependency behavior, and a small root facade without eager adapter imports.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/packaging.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "exports|subpath" + }, + { + "kind": "regex", + "value": "browser.*PostgreSQL.*ClickHouse|optional adapter" + }, + { + "kind": "regex", + "value": "type.*module|ESM" + }, + { + "kind": "regex", + "value": "types|declaration" + }, + { + "kind": "regex", + "value": "root.*(not|does not).*import|separate" + } + ], + "rubric": [ + "Creates explicit stable subpaths", + "Keeps runtime-specific integrations in leaves", + "Aligns JavaScript and declaration entrypoints" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "node-packages-official" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "packaging", + "training" + ], + "rationale": "Selective adoption depends on physical package boundaries." + }, + { + "id": "library-packaging-side-effects", + "title": "Audit side effects before declaring tree-shakability", + "skill": "build-libraries", + "kind": "knowledge", + "split": "valid-seen", + "prompt": "A package sets sideEffects:false but its root imports a generated registry, configures logging, reads environment variables, and registers browser adapters. Explain why the metadata is unsafe, redesign the entrypoints, and define artifact-level tree-shaking evidence beyond bundle size.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/packaging.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "sideEffects.*unsafe|truthful" + }, + { + "kind": "regex", + "value": "import.?time|top.?level" + }, + { + "kind": "regex", + "value": "metafile|module graph|marker" + }, + { + "kind": "regex", + "value": "clean consumer|packed artifact" + } + ], + "rubric": [ + "Treats side-effect metadata as a verified contract", + "Moves effects behind explicit entrypoints or calls", + "Uses module markers or graphs plus semantic execution" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "esbuild-tree-shaking-official", + "node-packages-official" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "packaging", + "tree-shaking", + "valid-seen" + ], + "rationale": "Metadata cannot compensate for an eagerly connected module graph." + }, + { + "id": "library-packaging-selective-fixture", + "title": "Repair selective package adoption", + "skill": "build-libraries", + "kind": "artifact", + "split": "test-frozen", + "prompt": "Repair the fixture package so the root and core subpath expose only the core analyze capability, the browser adapter is available from an explicit browser subpath, imports perform no global mutation, package side-effect metadata is truthful, and the verifier passes. Do not remove the browser capability.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/packaging.md" + ], + "assertions": [ + { + "kind": "command", + "command": [ + "node", + "verify.mjs" + ], + "expectedExitCode": 0 + } + ], + "rubric": [ + "Adds explicit root, core, and browser public entrypoints", + "Prevents root/core imports from traversing the browser adapter", + "Removes import-time mutation and declares side effects truthfully" + ], + "oracleStrength": "fixture-behavior", + "sourceIds": [ + "library-first-guidebook", + "node-packages-official", + "esbuild-tree-shaking-official" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "packaging", + "tree-shaking", + "frozen" + ], + "rationale": "Executable consumer behavior is stronger than source inspection.", + "fixture": "library-selective-adoption" + }, + { + "id": "library-recovery-ladder", + "title": "Classify restart resume and durable orchestration", + "skill": "build-libraries", + "kind": "knowledge", + "split": "train", + "prompt": "Classify three designs: an idempotent command reruns from the beginning, a library resumes from committed batch receipts, and a Temporal worker survives process loss with timers and signals. Define the authority and verification required for each and route durable execution ownership correctly.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/recovery-refactoring.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "restartable.*checkpoint|checkpoint.*durab" + }, + { + "kind": "regex", + "value": "committed.*receipt|checkpoint" + }, + { + "kind": "regex", + "value": "Temporal|workflow.*authority" + }, + { + "kind": "regex", + "value": "build-workflows|durable.*owner" + } + ], + "rubric": [ + "Names all three guarantees precisely", + "Keeps library checkpoint contracts distinct from durable execution", + "Requires persisted authority and crash evidence" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "temporal-typescript-official" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "recovery", + "training" + ], + "rationale": "Recovery claims must not collapse into one vague resumability label." + }, + { + "id": "library-recovery-commit-order", + "title": "Commit outputs before advancing checkpoints", + "skill": "build-libraries", + "kind": "trajectory", + "split": "valid-seen", + "prompt": "A resumable importer writes checkpoint N before flushing database batch N, and uses the current array index as its only identity. Redesign commit order, logical IDs, attempt IDs, output receipts, compatibility metadata, replay behavior, and startup reconciliation.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/recovery-refactoring.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "write.*output.*checkpoint|output.*before.*checkpoint" + }, + { + "kind": "regex", + "value": "logical.*attempt|attempt.*logical" + }, + { + "kind": "regex", + "value": "receipt|reconcile" + }, + { + "kind": "regex", + "value": "version|fingerprint|schema" + } + ], + "rubric": [ + "Prevents skipped output after crash", + "Separates logical work from attempts", + "Handles replay and incompatible resume" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "unstorage-1-17-5", + "ohash-2-0-11" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "recovery", + "valid-seen" + ], + "rationale": "Checkpoint position without durable output identity is fake resumability." + }, + { + "id": "library-refactor-cli-first", + "title": "Extract a reusable core without dual architecture", + "skill": "build-libraries", + "kind": "trajectory", + "split": "adversarial", + "prompt": "A team wants to move every CLI stage into packages/core, preserve all runBrowserPackage names, keep RuntimeContext public, and add wrappers so no callers change. Produce a phased refactor that preserves one command, writes desired library consumers first, classifies context fields, adds a second consumer, proves selective adoption, and removes compatibility scaffolding under an explicit policy.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/recovery-refactoring.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "characteri|preserve.*command|current behavior" + }, + { + "kind": "regex", + "value": "consumer.*first|desired.*call" + }, + { + "kind": "regex", + "value": "classif.*context|domain input.*capabilit" + }, + { + "kind": "regex", + "value": "second consumer" + }, + { + "kind": "regex", + "value": "remove.*compatib|legacy" + } + ], + "rubric": [ + "Does not equate package movement with extraction", + "Uses a vertical use-case migration", + "Avoids permanent dual orchestration and stale names" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "cli-audit" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "refactoring", + "cli", + "adversarial" + ], + "rationale": "Compatibility wrappers can preserve the architecture being removed." + }, + { + "id": "library-verification-claim-evidence", + "title": "Match library claims to executable evidence", + "skill": "build-libraries", + "kind": "trajectory", + "split": "train", + "prompt": "Create a verification matrix for a library that claims type-safe public APIs, import safety, tree-shaking, streaming, early-return cleanup, lower memory, and checkpoint resume. Name the minimum executable evidence for each claim and distinguish source review from artifact proof.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/verification.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "clean consumer|packed artifact" + }, + { + "kind": "regex", + "value": "tree.?shak.*(metafile|marker|graph)" + }, + { + "kind": "regex", + "value": "early return|slow.*sink|peak.*memory" + }, + { + "kind": "regex", + "value": "kill|crash.*checkpoint|restart" + } + ], + "rubric": [ + "Maps each claim to the right oracle", + "Includes artifact, lifecycle, performance, and crash evidence", + "Does not treat source inspection as runtime proof" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "verification", + "training" + ], + "rationale": "The skill must demand evidence proportional to the claim." + }, + { + "id": "library-verification-benchmark-gate", + "title": "Design a correctness-gated library benchmark", + "skill": "build-libraries", + "kind": "trajectory", + "split": "valid-seen", + "prompt": "A candidate data layout is 18% faster in one microbenchmark. Design the acceptance protocol for public parse, streaming, diagnostics, persistence, cold import, peak memory, retained memory, and error/cancellation paths. Include practical thresholds, protected workflows, raw artifacts, and rejection rules.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/verification.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "correctness.*gate|semantic.*oracle" + }, + { + "kind": "regex", + "value": "microbenchmark.*(not|cannot)|protected.*workflow" + }, + { + "kind": "regex", + "value": "threshold|guardrail" + }, + { + "kind": "regex", + "value": "raw.*sample|baseline|variab" + } + ], + "rubric": [ + "Keeps the microbenchmark explanatory rather than decisive", + "Predeclares practical and statistical decision rules", + "Protects memory, startup, errors, and full workflows" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "v8-performance-official" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "verification", + "performance", + "valid-seen" + ], + "rationale": "Fast wrong or locally optimized code is not a successful library change." + }, + { + "id": "library-verification-cross-skill", + "title": "Verify a library across CLI packaging and workflows", + "skill": "build-libraries", + "kind": "composition", + "split": "transfer", + "prompt": "A reusable analysis library is consumed by an Optique CLI, built with unbuild, logs through LogTape, stores checkpoint metadata in unstorage, and optionally runs inside Temporal. Produce one verification plan with correct owners for CLI behavior, package artifacts, ecosystem evidence, library resume contracts, and durable workflow execution.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/verification.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "build-clis|CLI.*owner" + }, + { + "kind": "regex", + "value": "build-devtools|pack.*artifact|clean consumer" + }, + { + "kind": "regex", + "value": "explore-ecosystems|source.*evidence" + }, + { + "kind": "regex", + "value": "build-workflows|Temporal.*durable" + }, + { + "kind": "regex", + "value": "library.*checkpoint|resume contract" + } + ], + "rubric": [ + "Uses one integrated plan without duplicate owners", + "Separates package evidence from public API evidence", + "Separates resumable library semantics from durable orchestration" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "cli-guidebook", + "temporal-typescript-official" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "verification", + "composition", + "transfer" + ], + "rationale": "Library completion often spans several existing domain skills." + }, + { + "id": "library-data-flow-cancellation-boundary", + "title": "Preserve cancellation and ownership across iterable-stream adapters", + "skill": "build-libraries", + "kind": "knowledge", + "split": "valid-unseen", + "prompt": "A library adapts an AsyncIterable into a ReadableStream for fetch integration. The current adapter keeps pulling after stream cancellation, materializes pending records, and leaves the source resource open when the reader releases its lock. Redesign the boundary and explain cancellation, return(), backpressure, buffering, and ownership semantics without pretending the two protocols are identical.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/data-flow.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "cancel.*(return|close|dispose)|return.*cancel" + }, + { + "kind": "regex", + "value": "backpressure|desiredSize|pull" + }, + { + "kind": "regex", + "value": "bounded.*buffer|buffer.*bound" + }, + { + "kind": "regex", + "value": "ownership|borrow|transfer" + }, + { + "kind": "not-contains", + "value": "AsyncIterable and ReadableStream are equivalent" + } + ], + "rubric": [ + "Treats protocol adaptation as a semantic boundary", + "Stops upstream production and cleanup on cancellation", + "Defines buffer and ownership behavior explicitly" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "whatwg-streams-standard", + "typescript-erm-official" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "data-flow", + "valid-unseen" + ], + "rationale": "A library can expose both protocols only if the adapter preserves cancellation, pressure, and lifetime semantics." + }, + { + "id": "library-packaging-runtime-registry-trap", + "title": "Reject a runtime-selected registry that defeats selective adoption", + "skill": "build-libraries", + "kind": "knowledge", + "split": "adversarial", + "prompt": "A package exposes createAdapter(name) and implements it by statically importing every database, browser, telemetry, and cloud adapter into one registry. The author argues runtime selection is maximally composable and bundlers will remove unused entries. Review the claim and design build-time selection, explicit subpaths, and an optional runtime-loading surface with truthful side-effect and dependency behavior.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/packaging.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "static.*registry.*retain|eager.*import" + }, + { + "kind": "regex", + "value": "subpath|explicit.*entry" + }, + { + "kind": "regex", + "value": "dynamic import|runtime loader" + }, + { + "kind": "regex", + "value": "metafile|clean consumer|bundle.*inspect" + }, + { + "kind": "regex", + "value": "sideEffects.*truth" + } + ], + "rubric": [ + "Distinguishes build-time selective adoption from runtime plugin selection", + "Keeps the common root free of optional adapter dependency graphs", + "Requires artifact-level proof rather than bundler optimism" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "node-packages-official", + "esbuild-tree-shaking-official" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "packaging", + "adversarial" + ], + "rationale": "Runtime registries are a common way to turn conceptual optionality into physical dependency retention." + }, + { + "id": "route-build-libraries-public-api", + "title": "Route a reusable package redesign", + "skill": "build-libraries", + "kind": "routing", + "split": "valid-unseen", + "prompt": "Refactor a CLI-owned TypeScript core into a public ESM library with async iterables, explicit resource ownership, optional browser adapters, and tree-shaking tests.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [], + "forbiddenReferences": [], + "assertions": [ + { + "kind": "contains", + "value": "build-libraries" + } + ], + "rubric": [ + "Activates the library skill" + ], + "oracleStrength": "routing-smoke", + "sourceIds": [ + "library-first-guidebook" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "routing" + ], + "rationale": "Public reusable package work should activate the focused skill." + }, + { + "id": "route-library-incidental-helper-negative", + "title": "Do not route an incidental private helper", + "skill": "build-libraries", + "kind": "routing", + "split": "adversarial", + "prompt": "Rename one private formatDate helper inside an application. It has one caller and no public or reusable contract.", + "expectedSkills": [], + "forbiddenSkills": [ + "build-libraries" + ], + "requiredReferences": [], + "forbiddenReferences": [], + "assertions": [ + { + "kind": "not-contains", + "value": "build-libraries" + } + ], + "rubric": [ + "Avoids activating a heavyweight library workflow for an incidental helper" + ], + "oracleStrength": "routing-smoke", + "sourceIds": [ + "library-first-guidebook" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "routing", + "negative" + ], + "rationale": "The skill explicitly excludes incidental internal helpers." + }, + { + "id": "route-cli-flag-without-library-negative", + "title": "Keep a CLI-only flag in the CLI skill", + "skill": "composition", + "kind": "routing", + "split": "adversarial", + "prompt": "Add --quiet and generated shell completion to an existing Optique CLI. No reusable API or package boundary changes.", + "expectedSkills": [ + "build-clis" + ], + "forbiddenSkills": [ + "build-libraries" + ], + "requiredReferences": [], + "forbiddenReferences": [], + "assertions": [ + { + "kind": "contains", + "value": "build-clis" + }, + { + "kind": "not-contains", + "value": "build-libraries" + } + ], + "rubric": [ + "Routes public command language without inventing library work" + ], + "oracleStrength": "routing-smoke", + "sourceIds": [ + "cli-guidebook" + ], + "evidenceStatus": "normative", + "tags": [ + "build-clis", + "build-libraries", + "routing", + "negative" + ], + "rationale": "CLI product changes do not automatically require a reusable library redesign." + }, + { + "id": "composition-library-cli-extraction", + "title": "Compose delivery CLI and library ownership", + "skill": "composition", + "kind": "trajectory", + "split": "valid-unseen", + "prompt": "Implement a refactor that keeps an Optique CLI runnable while extracting a reusable analysis library, preserving c12 precedence and LogTape routing, adding package subpaths and clean-consumer tests, and removing the old runtime API after parity.", + "expectedSkills": [ + "deliver-software", + "build-clis", + "build-libraries", + "build-devtools" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/recovery-refactoring.md", + "build-clis/references/architecture.md", + "build-devtools/references/packaging.md" + ], + "forbiddenReferences": [], + "assertions": [ + { + "kind": "regex", + "value": "one.*plan|ownership" + }, + { + "kind": "regex", + "value": "CLI.*c12.*LogTape" + }, + { + "kind": "regex", + "value": "clean consumer|package subpath" + }, + { + "kind": "regex", + "value": "remove.*runtime|legacy" + } + ], + "rubric": [ + "Uses one repository discovery and integrated plan", + "Keeps command/config/output ownership in the CLI", + "Carries implementation through package proof and cleanup" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "cli-guidebook" + ], + "evidenceStatus": "normative", + "tags": [ + "composition", + "build-libraries", + "build-clis", + "build-devtools" + ], + "rationale": "The most common migration requires several skills with non-overlapping owners." + }, + { + "id": "composition-library-durable-workflow", + "title": "Separate library resume from durable workflow authority", + "skill": "composition", + "kind": "trajectory", + "split": "adversarial", + "prompt": "A library exposes resume(checkpoint), and a team claims this makes its 12-hour import durable. Design the library checkpoint contract and the Temporal worker/control-plane integration, including idempotent effects, versioning, operator controls, and crash verification.", + "expectedSkills": [ + "build-libraries", + "build-workflows" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/recovery-refactoring.md", + "build-workflows/references/durability.md" + ], + "forbiddenReferences": [], + "assertions": [ + { + "kind": "regex", + "value": "library.*checkpoint|resume contract" + }, + { + "kind": "regex", + "value": "workflow.*authority|Temporal" + }, + { + "kind": "regex", + "value": "idempot|operator|version" + }, + { + "kind": "regex", + "value": "kill|restart|crash" + } + ], + "rubric": [ + "Rejects the false durability claim", + "Keeps public resume semantics in the library", + "Assigns persisted execution and operator recovery to the workflow skill" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "temporal-typescript-official" + ], + "evidenceStatus": "normative", + "tags": [ + "composition", + "build-libraries", + "build-workflows", + "durability" + ], + "rationale": "Checkpoint APIs and durable execution are adjacent but distinct." + }, + { + "id": "composition-library-ecosystem-selection", + "title": "Research an ecosystem for a library integration", + "skill": "composition", + "kind": "trajectory", + "split": "transfer", + "prompt": "Choose the smallest LogTape and UnJS package set for a reusable SDK that needs library-safe diagnostics, project config in its CLI adapter, optional checkpoint storage, and no plugin system. Inspect official siblings and exclusions, then define the library boundaries.", + "expectedSkills": [ + "build-libraries", + "explore-ecosystems", + "build-clis" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/composition.md", + "explore-ecosystems/references/selection.md", + "build-clis/references/ecosystems.md" + ], + "forbiddenReferences": [], + "assertions": [ + { + "kind": "regex", + "value": "LogTape.*library|not.*configure" + }, + { + "kind": "regex", + "value": "c12|defu|unstorage" + }, + { + "kind": "regex", + "value": "exclude|smallest coherent" + }, + { + "kind": "regex", + "value": "no.*Hookable|plugin.*not" + } + ], + "rubric": [ + "Maps the ecosystems before selecting packages", + "Keeps configuration in the CLI adapter", + "Avoids installing extension machinery without a requirement" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "logtape-official", + "c12-official", + "unstorage-1-17-5" + ], + "evidenceStatus": "observed-source", + "tags": [ + "composition", + "build-libraries", + "explore-ecosystems", + "build-clis" + ], + "rationale": "Library composition and ecosystem topology need separate owners." + }, + { + "id": "composition-library-release-frozen", + "title": "Deliver a selective resumable library and CLI", + "skill": "composition", + "kind": "artifact", + "split": "test-frozen", + "prompt": "Plan and implement a Deno-first strict TypeScript library extracted from a CLI. Preserve a thin Optique/c12/LogTape CLI adapter, expose side-effect-free ESM core and browser subpaths, use bounded async batches with deterministic cleanup, define checkpoint-resume but route durable execution separately, build and pack the artifact, verify clean consumers and tree-shaking, and remove the old public runtime/stage API.", + "expectedSkills": [ + "deliver-software", + "deno-software", + "build-clis", + "build-libraries", + "build-devtools", + "build-workflows" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/architecture.md", + "build-libraries/references/data-flow.md", + "build-libraries/references/resources-performance.md", + "build-libraries/references/packaging.md", + "build-libraries/references/recovery-refactoring.md" + ], + "forbiddenReferences": [], + "assertions": [ + { + "kind": "regex", + "value": "thin.*CLI|Optique.*c12.*LogTape" + }, + { + "kind": "regex", + "value": "subpath|side.?effect|tree.?shak" + }, + { + "kind": "regex", + "value": "bounded.*batch|AsyncIterable|cleanup" + }, + { + "kind": "regex", + "value": "checkpoint.*durable.*workflow|workflow.*separate" + }, + { + "kind": "regex", + "value": "clean consumer|pack" + }, + { + "kind": "regex", + "value": "remove.*stage|runtime" + } + ], + "rubric": [ + "Produces one integrated implementation and cleanup plan", + "Preserves all specialist ownership boundaries", + "Requires executable package, lifecycle, performance, and recovery evidence" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "cli-guidebook", + "deno-software", + "temporal-typescript-official" + ], + "evidenceStatus": "normative", + "tags": [ + "composition", + "build-libraries", + "frozen", + "release" + ], + "rationale": "Frozen cross-skill topology for the full library-first migration." + }, + { + "id": "library-architecture-justify-boundary", + "title": "Justify a library boundary without slogans", + "skill": "build-libraries", + "kind": "trajectory", + "split": "valid-unseen", + "prompt": "A team says library-first architecture is necessary and proposes splitting every internal module into a separately published package. Evaluate and justify the boundary decision. Name the protected objective, hard constraints, diagnosis and causal chain, credible alternatives including doing nothing or a reversible pilot, exact rejection reasons, accepted trade-offs, assumptions or defeaters, and whether the proposal is necessary, conditionally necessary, prudent, preferred, or unjustified.", + "expectedSkills": [ + "build-libraries" + ], + "forbiddenSkills": [], + "requiredReferences": [ + "build-libraries/references/architecture.md" + ], + "assertions": [ + { + "kind": "regex", + "value": "objective|failure condition|protected" + }, + { + "kind": "regex", + "value": "hard constraint|preference" + }, + { + "kind": "regex", + "value": "do nothing|inaction|delay|pilot|partial" + }, + { + "kind": "regex", + "value": "trade.?off|cost|risk" + }, + { + "kind": "regex", + "value": "assumption|defeater|would change" + }, + { + "kind": "regex", + "value": "conditionally necessary|prudent|preferred|unjustified" + }, + { + "kind": "not-contains", + "value": "because it is best practice" + } + ], + "rubric": [ + "Connects the situation, mechanism, constraints, and evidence to the boundary decision", + "Compares weaker and more reversible options before accepting package proliferation", + "Qualifies the conclusion and exposes evidence that would change it" + ], + "oracleStrength": "trajectory-rubric", + "sourceIds": [ + "library-first-guidebook", + "decision-justification-guide" + ], + "evidenceStatus": "normative", + "tags": [ + "build-libraries", + "architecture", + "decision-quality", + "valid-unseen" + ], + "rationale": "Library-first language must not become an unexamined package-splitting slogan." + } + ] +} diff --git a/evals/fixtures/library-selective-adoption/README.md b/evals/fixtures/library-selective-adoption/README.md new file mode 100644 index 0000000..ce42549 --- /dev/null +++ b/evals/fixtures/library-selective-adoption/README.md @@ -0,0 +1,5 @@ +# Selective adoption fixture + +The root package should expose the core facade without importing the browser +adapter. The browser adapter must remain available from an explicit public +subpath. Importing either entrypoint must not mutate global state. diff --git a/evals/fixtures/library-selective-adoption/package.json b/evals/fixtures/library-selective-adoption/package.json new file mode 100644 index 0000000..8b1ec0d --- /dev/null +++ b/evals/fixtures/library-selective-adoption/package.json @@ -0,0 +1,8 @@ +{ + "name": "@fixture/selective-library", + "private": true, + "type": "module", + "exports": { + ".": "./src/index.mjs" + } +} diff --git a/evals/fixtures/library-selective-adoption/src/browser.mjs b/evals/fixtures/library-selective-adoption/src/browser.mjs new file mode 100644 index 0000000..bcd413e --- /dev/null +++ b/evals/fixtures/library-selective-adoption/src/browser.mjs @@ -0,0 +1,5 @@ +globalThis.__fixtureBrowserAdapterLoaded = true; + +export function createBrowserAdapter() { + return { kind: "browser" }; +} diff --git a/evals/fixtures/library-selective-adoption/src/core.mjs b/evals/fixtures/library-selective-adoption/src/core.mjs new file mode 100644 index 0000000..1a0d1eb --- /dev/null +++ b/evals/fixtures/library-selective-adoption/src/core.mjs @@ -0,0 +1,3 @@ +export function analyze(values) { + return values.reduce((sum, value) => sum + value, 0); +} diff --git a/evals/fixtures/library-selective-adoption/src/index.mjs b/evals/fixtures/library-selective-adoption/src/index.mjs new file mode 100644 index 0000000..604bfc7 --- /dev/null +++ b/evals/fixtures/library-selective-adoption/src/index.mjs @@ -0,0 +1,2 @@ +export { analyze } from "./core.mjs"; +export { createBrowserAdapter } from "./browser.mjs"; diff --git a/evals/fixtures/library-selective-adoption/verify.mjs b/evals/fixtures/library-selective-adoption/verify.mjs new file mode 100644 index 0000000..7ab9cc9 --- /dev/null +++ b/evals/fixtures/library-selective-adoption/verify.mjs @@ -0,0 +1,51 @@ +import assert from "node:assert/strict"; +import { readFile } from "node:fs/promises"; +import { spawnSync } from "node:child_process"; + +const manifest = JSON.parse(await readFile("package.json", "utf8")); +assert.equal(manifest.type, "module"); +assert.equal(manifest.sideEffects, false); +assert.equal(typeof manifest.exports, "object"); +assert.ok(manifest.exports["."]); +assert.ok(manifest.exports["./core.js"]); +assert.ok(manifest.exports["./browser.js"]); + +function run(source) { + const result = spawnSync(process.execPath, ["--input-type=module", "-e", source], { + cwd: process.cwd(), + encoding: "utf8", + }); + assert.equal(result.status, 0, result.stderr || result.stdout); + return result.stdout.trim(); +} + +assert.equal( + run(` + import { analyze } from "@fixture/selective-library/core.js"; + if (globalThis.__fixtureBrowserAdapterLoaded) throw new Error("browser adapter loaded from core"); + console.log(analyze([1, 2, 3])); + `), + "6", +); + +assert.equal( + run(` + import { analyze } from "@fixture/selective-library"; + if (globalThis.__fixtureBrowserAdapterLoaded) throw new Error("browser adapter loaded from root"); + console.log(analyze([2, 3])); + `), + "5", +); + +assert.equal( + run(` + import { createBrowserAdapter } from "@fixture/selective-library/browser.js"; + if (globalThis.__fixtureBrowserAdapterLoaded) throw new Error("browser import mutated globals"); + console.log(createBrowserAdapter().kind); + `), + "browser", +); + +const rootSource = await readFile("src/index.mjs", "utf8"); +assert.doesNotMatch(rootSource, /browser\.mjs/); +console.log("selective adoption verified"); diff --git a/evals/fixtures/library-streaming-cleanup/README.md b/evals/fixtures/library-streaming-cleanup/README.md new file mode 100644 index 0000000..abc83c7 --- /dev/null +++ b/evals/fixtures/library-streaming-cleanup/README.md @@ -0,0 +1,5 @@ +# Streaming cleanup fixture + +`collectItems()` must return an async iterable. It should acquire the resource +only when iteration begins, read one item at a time, stop producing after the +consumer breaks, and dispose through `Symbol.asyncDispose` exactly once. diff --git a/evals/fixtures/library-streaming-cleanup/src/collect.mjs b/evals/fixtures/library-streaming-cleanup/src/collect.mjs new file mode 100644 index 0000000..98851e5 --- /dev/null +++ b/evals/fixtures/library-streaming-cleanup/src/collect.mjs @@ -0,0 +1,9 @@ +export async function collectItems(items, acquire) { + const resource = await acquire(); + const values = []; + for (const item of items) { + values.push(await resource.read(item)); + } + await resource.close(); + return values; +} diff --git a/evals/fixtures/library-streaming-cleanup/verify.mjs b/evals/fixtures/library-streaming-cleanup/verify.mjs new file mode 100644 index 0000000..e7caac7 --- /dev/null +++ b/evals/fixtures/library-streaming-cleanup/verify.mjs @@ -0,0 +1,54 @@ +import assert from "node:assert/strict"; +import { collectItems } from "./src/collect.mjs"; + +let acquired = 0; +let reads = 0; +let disposed = 0; + +const output = collectItems([1, 2, 3, 4], async () => { + acquired++; + return { + async read(value) { + reads++; + await Promise.resolve(); + return value * 2; + }, + async [Symbol.asyncDispose]() { + disposed++; + }, + }; +}); + +assert.equal(acquired, 0, "resource acquisition must be lazy"); +assert.equal(typeof output?.[Symbol.asyncIterator], "function", "must return AsyncIterable"); + +const values = []; +for await (const value of output) { + values.push(value); + if (values.length === 2) break; +} + +assert.deepEqual(values, [2, 4]); +assert.equal(acquired, 1); +assert.equal(reads, 2, "early return must stop upstream reads"); +assert.equal(disposed, 1, "resource must be disposed exactly once"); + +let failureDisposed = 0; +const failing = collectItems([1, 2], async () => ({ + async read(value) { + if (value === 2) throw new Error("read failed"); + return value; + }, + async [Symbol.asyncDispose]() { + failureDisposed++; + }, +})); + +await assert.rejects(async () => { + for await (const _value of failing) { + // Consume until the source fails. + } +}, /read failed/); +assert.equal(failureDisposed, 1, "failure must dispose the resource"); + +console.log("streaming cleanup verified"); diff --git a/evals/sources.json b/evals/sources.json index 6249e54..c5f2e02 100644 --- a/evals/sources.json +++ b/evals/sources.json @@ -594,6 +594,80 @@ "status": "normative", "role": "Deno-specific composition and verification contract", "verifiedDate": "2026-07-13" + }, + { + "id": "library-first-guidebook", + "artifact": "library_first_architecture_guidebook.md", + "kind": "guidebook", + "status": "normative", + "role": "Composable tree-shakable data-oriented library architecture, resource, performance, recovery, and refactoring contract", + "verifiedDate": "2026-07-23", + "sha256": "9656d1394a720dbaaa8604d9316454c20ac566e6d4f299ea0812e941d4aa4f48" + }, + { + "id": "typescript-erm-official", + "artifact": "https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html", + "kind": "official-docs", + "status": "observed-source", + "role": "TypeScript explicit resource management, using, await using, DisposableStack, and AsyncDisposableStack", + "verifiedDate": "2026-07-23" + }, + { + "id": "node-packages-official", + "artifact": "https://nodejs.org/api/packages.html", + "kind": "official-docs", + "status": "observed-source", + "role": "Node package exports, subpath exports, conditional exports, and public package encapsulation", + "verifiedDate": "2026-07-23" + }, + { + "id": "esbuild-tree-shaking-official", + "artifact": "https://esbuild.github.io/api/#tree-shaking", + "kind": "official-docs", + "status": "observed-source", + "role": "esbuild ESM tree-shaking, conservative side-effect analysis, package sideEffects metadata, and metafile evidence", + "verifiedDate": "2026-07-23" + }, + { + "id": "whatwg-streams-standard", + "artifact": "https://streams.spec.whatwg.org/", + "kind": "official-docs", + "status": "normative", + "role": "Readable, writable, and transform stream backpressure, cancellation, locking, and async iteration semantics", + "verifiedDate": "2026-07-23" + }, + { + "id": "data-oriented-design-book", + "artifact": "https://www.dataorienteddesign.com/dodbook/", + "kind": "guidebook", + "status": "normative", + "role": "Data-oriented transform, representation, access-pattern, locality, allocation, and hardware-aware design model", + "verifiedDate": "2026-07-23" + }, + { + "id": "v8-performance-official", + "artifact": "https://v8.dev/blog/fast-properties", + "kind": "official-docs", + "status": "observed-source", + "role": "V8 object shapes, properties, elements, allocation, and runtime representation performance evidence", + "verifiedDate": "2026-07-23" + }, + { + "id": "semver-official", + "artifact": "https://semver.org/", + "kind": "official-docs", + "status": "normative", + "role": "Explicit public API and compatibility versioning contract", + "verifiedDate": "2026-07-23" + }, + { + "id": "decision-justification-guide", + "artifact": "how-to-justify-decisions-properly(1).md", + "kind": "guidebook", + "status": "normative", + "role": "Architecture decision objectives, constraints, causal diagnosis, alternatives, trade-offs, defeaters, and conditional-necessity discipline", + "verifiedDate": "2026-07-23", + "sha256": "f8166af2e7d468e1195369c3db9889640b00fc79972f816530d23255a608d5a4" } ] } diff --git a/reports/build-libraries-initialization.md b/reports/build-libraries-initialization.md new file mode 100644 index 0000000..578dc42 --- /dev/null +++ b/reports/build-libraries-initialization.md @@ -0,0 +1,172 @@ +# Build Libraries skill initialization + +## Scope + +This change adds a focused `build-libraries` skill for designing, extracting, +reviewing, packaging, and verifying reusable TypeScript and JavaScript +libraries. It is intentionally separate from CLI interface design, generic +delivery policy, developer-tool packaging automation, ecosystem research, data +platform design, and durable workflow execution. + +The skill incorporates the library-first architecture guidebook and the attached +decision-justification guidance. It treats “library first,” “composable,” +“streaming,” and “tree-shakable” as claims that require a concrete objective, +constraints, alternatives, trade-offs, and executable evidence. + +## Accepted skill surface + +The skill routes eight material references: + +1. use-case-first architecture, information hiding, deep modules, and qualified + boundary decisions; +2. composition across values, data flow, capabilities, policies, ecosystems, + lifecycles, package graphs, and operations; +3. values, arrays, iterables, generators, async iterables, streams, batching, + materialization, backpressure, cancellation, and early termination; +4. transform-first data-oriented design, hot and cold data, indexing, + allocation, locality, and public-to-internal representation boundaries; +5. explicit resource ownership, `Disposable`, `AsyncDisposable`, `using`, + `await using`, partial-construction cleanup, concurrency, buffering, and + performance budgets; +6. ESM exports, public subpaths, side-effect metadata, adapter isolation, + declaration reachability, clean consumers, and tree-shaking evidence; +7. restartable, checkpoint-resumable, and durably orchestrated execution plus a + phased CLI-first extraction process; +8. source, artifact, runtime, lifecycle, workload, recovery, compatibility, and + cross-skill verification. + +## Ecosystem position + +The skill preserves strategic ecosystem semantics instead of wrapping every +package behind a lowest-common-denominator interface: + +- LogTape supplies structured library diagnostics, categories, contexts, + filters, sinks, redaction, and lifecycle behavior. Applications configure the + logging graph. +- c12 discovers and resolves configuration layers. defu may participate in an + application-owned merge algebra. Libraries receive validated resolved values. +- unstorage supplies selectable storage drivers, but the library contract states + the actual durability, atomicity, and checkpoint semantics required. +- Hookable is reserved for real extension protocols rather than internal code + organization. +- Optique remains owned by `build-clis` as the executable command-language + adapter. + +## Ownership boundaries + +Routing changes establish these boundaries: + +- `deliver-software` selects `build-libraries` for library, SDK, extraction, + public API, tree-shaking, streaming, resource-lifetime, performance, and + resumability work. +- `build-clis` owns argv, help, interaction, configuration sources, terminal + output, process signals, and exits. It does not own the reusable programming + model. +- `build-devtools` owns build, package, release, and generated developer-tool + surfaces. `build-libraries` owns the meaning of the public API and selective + adoption contract. +- `build-workflows` owns persisted execution authority, worker reachability, + retries, timers, signals, and operator recovery. `build-libraries` owns + restartable and checkpoint-resumable operation contracts that may be hosted by + that workflow layer. +- `explore-ecosystems` remains the owner for broad package-family topology and + package selection research. + +## Evaluation surface + +`evals/cases/library-design-deep.json` contains 34 cases: + +- 8 train; +- 8 valid-seen; +- 6 valid-unseen; +- 7 adversarial; +- 2 transfer; +- 3 test-frozen. + +The cases include 29 direct `build-libraries` cases and 5 cross-skill +composition cases. Eight capability records connect every material reference to +its sources, decision questions, failure signatures, exclusions, and +verification method. + +The held-out decision case requires an architecture recommendation to expose its +objective, hard constraints, diagnosis, alternatives, rejection reasons, +trade-offs, assumptions, defeaters, and qualified decision classification. It +prevents package proliferation from being justified by “library first” alone. + +## Executable frozen fixtures + +### Selective adoption + +`evals/fixtures/library-selective-adoption` begins with an intentionally broken +package whose root entrypoint eagerly reaches a browser adapter and whose module +mutates global state. The oracle requires: + +- ESM package identity; +- root, core, and browser public subpaths; +- truthful `sideEffects: false` metadata; +- core and root imports that do not load the browser adapter; +- explicit browser import without global mutation. + +### Streaming cleanup + +`evals/fixtures/library-streaming-cleanup` begins with an intentionally eager +`Promise` implementation. The oracle requires: + +- lazy resource acquisition; +- an `AsyncIterable` result; +- one read per consumed value; +- upstream stop after early termination; +- exactly-once asynchronous disposal; +- disposal after failure. + +Both fixtures reject their broken state and pass after their expected fixes are +applied in temporary copies. + +## Verification completed + +The following checks were actually run: + +- JSON parsing for the new case corpus, capability registry, and source registry; +- custom repository validation equivalent to the deterministic structural rules + in `scripts/validate.ts`; +- custom SkillOpt matrix validation for reference coverage, root routing, and + frozen composition topology; +- Node syntax checks for all new `.mjs` fixture files; +- broken-state oracle checks for both executable fixtures; +- corrected-state oracle checks in temporary copies for both fixtures; +- SHA-256 verification for the library-first guidebook and attached + decision-justification source; +- trailing whitespace, final newline, CRLF, and em-dash checks across all changed + files; +- generated-state checks for `.skillopt`, Python caches, and macOS metadata. + +The structural validator reported: + +```text +Checked 13 skills, 544 cases, 16 executable, 52 frozen, +80 capabilities, 70 sources. +Custom repository validation passed. +``` + +The matrix validator reported: + +```text +Matrix checked 54 capability references, 13 root routers, +and 3 frozen composition topologies. +Custom SkillOpt matrix validation passed. +``` + +## Blocked or not run + +- The environment does not contain a Deno executable. Network restrictions also + prevented installing one. Therefore `deno task check`, `deno task test`, + `deno task validate`, and `deno task skillopt:matrix` were not run through the + repository's native Deno task chain. +- Full `sources:verify` was not run because it requires the complete historical + attachment directory. The two newly registered local source digests were + verified directly. +- External model rollouts, LLM judging, cross-model evaluation, and SkillOpt + optimization were not available. No model-quality improvement is claimed. + +These are release blockers for a final optimized skill release, but not hidden +as successful checks in this handoff. -- 2.51.2