@hobin/developer 0.1.10 → 0.1.12

package/skills/sketch/reference-policy.json

@@ -4,12 +4,12 @@
     {
       "id": "data-driven-design",
       "question": "How do accepted data meanings and examples determine the first executable function surface?",
-      "trigger": "Product information, variants, examples, or tests should determine the function skeleton, and no narrower template, composition, generation, or accumulator question is primary.",
+      "trigger": "Product information, variants, examples, or tests should determine the function skeleton, and no narrower template, composition, generation, accumulator, or evidence-preserving boundary question is primary.",
       "method_step": "derive data definition, interpretation, examples, purpose, template, completed shape, and first executable item",
       "references": ["references/data-driven-design.md"],
       "artifacts": ["the six ordered design artifacts", "repository contradictions mapped to those artifacts", "a bounded first item and propagation check"],
       "stop": "Accepted data and behavior examples constrain an executable skeleton with contradictions and compatibility visible.",
-      "separate_when": "Template shape, composition, earned abstraction, generated problems, or accumulated knowledge has an independent artifact."
+      "separate_when": "Template shape, composition, earned abstraction, generated problems, accumulated knowledge, or raw-to-refined construction has an independent artifact."
     },
     {
       "id": "data-shape-template",
@@ -66,6 +66,16 @@
       "stop": "The invariant explains initial, step, and final states and every semantic/resource delta is explicit.",
       "separate_when": "Problems are generated, carried data is persistent product history, or a concrete cache surface needs review."
     },
+    {
+      "id": "evidence-preserving-boundary",
+      "question": "How does less-trusted or less-structured input become a domain value that carries the established invariant?",
+      "trigger": "External, serialized, persisted, legacy, foreign, unknown, nullable, or overly broad input must become an accepted domain value; checks are repeated, return no refined value, occur after effects, or are followed by an assertion, cast, non-null claim, unchecked decode, or public raw construction.",
+      "method_step": "derive raw provenance, refined representation, parser or smart-constructor success/failure, construction owner, first-effect boundary, escape audit, and any bounded compiler gap",
+      "references": ["references/evidence-preserving-boundaries.md"],
+      "artifacts": ["a raw-to-refined boundary pipeline", "a parser/smart-constructor and failure contract", "a construction/escape, effect-order, and trusted-compiler-gap audit"],
+      "stop": "Every core construction path returns the invariant-carrying representation or explicit failure before dependent effects, with no unchecked narrowing or public raw-constructor bypass.",
+      "separate_when": "Admitted values or failure policy are disputed, alternate representations/public laws are independently consequential, a valid domain event changes type, or old/new compatibility remains unsettled."
+    },
     {
       "id": "design-levels",
       "question": "Which vocabulary, owner, and dependency direction make this caller contract truthful?",
@@ -74,7 +84,7 @@
       "references": ["references/design-levels-and-boundaries.md"],
       "artifacts": ["a caller-purpose and level map", "contract/owner/hidden choice/assumptions", "an alternate implementation or falsifier"],
       "stop": "Dependencies use truthful vocabulary, guarantees have owners, and lower-level change does not force unrelated callers.",
-      "separate_when": "Representation, closure, process, state, dispatch, conversion, language, runtime, responsibility, or variation has its own output."
+      "separate_when": "Evidence-preserving input refinement, representation, closure, process, state, dispatch, conversion, language, runtime, responsibility, or variation has its own output."
     },
     {
       "id": "representation-barrier",

package/skills/sketch/references/evidence-preserving-boundaries.md

@@ -0,0 +1,200 @@
+# Evidence-Preserving Boundaries
+
+Use this reference when less-trusted or less-structured input must become a domain
+value whose type or abstract representation carries an accepted invariant. The
+input may be bytes, JSON, form values, command-line arguments, database rows,
+legacy records, framework payloads, foreign values, or an overly broad in-memory
+type. Parsing here means any fallible transformation from a weaker
+representation to a stronger one; it is not limited to text.
+
+## Information Must Survive The Check
+
+Two operations may perform the same runtime checks while establishing different
+contracts:
+
+```text
+validate : Raw -> Result<Unit, BoundaryError>
+parse    : Raw -> Result<Domain, BoundaryError>
+```
+
+`validate` reports only success or failure. Unless its result narrows the value
+in a scope the compiler preserves, later code still receives `Raw` and must
+repeat the check, trust a comment, or assert `Domain`. `parse` returns the more
+precise value and makes the learned information necessary for execution.
+
+Treat these as evidence-destroying by default:
+
+```text
+validate(raw); cast raw to Domain
+JSON.decode(bytes) as Domain
+lookup(key)! where absence has domain meaning
+construct Domain through public raw fields
+```
+
+A type assertion, cast, non-null assertion, ignored conversion result, or typed
+deserialization target is not evidence that an invariant holds.
+
+## Draw The Refinement Boundary
+
+Derive this pipeline before choosing library syntax:
+
+```text
+external / raw / legacy representation
+                |
+                | parse / refine / smart constructor
+                | failure is explicit here
+                v
+       invariant-carrying domain value
+                |
+                | total core operations
+                v
+             domain effects
+```
+
+Record:
+
+```text
+raw representation and provenance
+accepted domain representation
+invariant learned at the transition
+parser or smart-constructor signature
+success and failure result
+single construction owner
+first domain effect allowed after success
+legacy, persistence, and re-entry paths
+```
+
+Push the proof burden toward the earliest boundary that has enough information,
+but no further. Authorization or a small resource guard may precede expensive
+parsing when abuse resistance requires it; those checks must not perform the
+domain mutation that depends on parsed input. Parsing may use several passes or
+select a later parser from an earlier discriminator as long as execution does
+not consume partially parsed domain data.
+
+## Choose A Stronger Representation
+
+Prefer the most precise representation the current language and repository can
+reasonably support:
+
+- a product type when required fields must be present together;
+- a sum type when cases have different meanings or fields;
+- a non-empty, bounded, normalized, branded, opaque, or capability-bearing type
+  when that restriction removes a real downstream branch;
+- a map or set when uniqueness or duplicate policy is accepted;
+- an abstract type with a smart constructor when the host type system cannot
+  directly encode the invariant.
+
+Do not call a narrower representation better until the excluded ability is known
+to be unnecessary. The accepted domain comes from `model`; this route owns the
+boundary that constructs it.
+
+## Wished Interface
+
+Use the target language's ordinary result and error conventions. The important
+shape is that success carries `Domain`:
+
+```text
+parseOrder : UnknownInput -> Result<Order, OrderInputError>
+placeOrder : Order -> Effect<PlacementResult>
+
+handle(input):
+  order <- parseOrder(input)
+  placeOrder(order)
+```
+
+Throwing at an application edge, returning an option/either/result, or using a
+checked constructor can all be valid. A predicate or assertion function can also
+preserve information when the language genuinely narrows the checked value in
+the only scope where it is consumed. What is not valid is checking one value and
+then separately claiming a stronger type without a compiler-visible or
+abstraction-visible connection.
+
+## Construction And Escape Audit
+
+List every way `Domain` can enter the core:
+
+| Path | Input provenance | Establishes invariant by | Produces | Bypass risk |
+| --- | --- | --- | --- | --- |
+| public parser | external raw value | complete boundary checks | `Domain` or failure | expected path |
+| smart constructor | broad in-memory value | constructor checks | abstract `Domain` or failure | expected path |
+| deserializer | persisted or wire value | parser plus compatibility policy | `Domain` or failure | unchecked typed decode |
+| internal constructor | already refined fields | private construction law | `Domain` | public/raw export |
+| test factory | test data | public or equivalent checked path | `Domain` | unrealistic invalid fixtures |
+
+A claimed invariant is only as strong as its weakest construction path. Search
+for raw constructors, object literals, reflection, ORM hydration, generated
+adapters, test factories, casts, suppressions, and legacy re-entry points.
+
+## Trusted Compiler Gaps
+
+Sometimes a complete check establishes a fact that the host type system cannot
+retain. Do not spread assertions to compensate. Isolate the smallest exception
+inside the one parser or smart-constructor owner and record:
+
+```text
+exact assertion or unsafe operation
+fact already established
+complete check or trusted contract that established it
+why ordinary narrowing cannot express the fact
+containment boundary
+falsifying test, type check, or structural inspection
+```
+
+Literal-preservation syntax and framework types already guaranteed by a runtime
+schema are not the same as asserting hostile input into a domain type. The
+burden is still on the exception to name its prior evidence. If that evidence is
+missing, return to the parser design instead of documenting a wish.
+
+## Shotgun And Effect Check
+
+Reject a design when parsing or validation is mixed through processing code:
+
+- consumers repeat checks for the same invariant;
+- a late branch can discover malformed input after writes, sends, or mutations;
+- every core function reserves an "impossible" failure despite an earlier check;
+- compatibility adapters emit partially refined values;
+- normalized and raw forms remain mutable and can drift apart.
+
+Parse before the first domain effect. If staging or streaming makes one complete
+up-front parse impractical, define an explicit phase or transaction boundary and
+ensure each effect consumes a value whose required invariant is already carried
+by that phase's representation.
+
+## Artifact
+
+```text
+Raw representation and provenance:
+Refined domain representation:
+Invariant gained and ability lost:
+Parser/smart-constructor signature:
+Failure representation:
+Construction owner and escape audit:
+First domain effect after success:
+Legacy/persistence/re-entry handling:
+Trusted compiler gaps, or none:
+Negative, bypass, and effect-order checks:
+```
+
+## Stop And Separation
+
+Stop when every core construction path either produces the refined domain value
+through the declared parser/constructor or fails explicitly, invalid input is
+rejected before the domain effect that depends on it, and no unchecked narrowing
+or public raw constructor claims the invariant.
+
+Return to `model` when the admitted values or failure policy are disputed. Use
+`representation-barrier` when alternate internal representations and public laws
+are independently consequential, `type-transition` when an accepted domain
+event transforms one valid domain type into another, and `contract-replacement`
+when old and new boundary compatibility remains unsettled.
+
+## Source Trace
+
+- Alexis King, “Parse, don’t validate,” published November 5, 2019: the
+  `NonEmpty` example, validation-versus-parsing return-type contrast, boundary
+  parsing and shotgun-parsing discussion, practical duplicate-key example, and
+  guidance on precise datatypes, proof placement, multi-pass parsing,
+  denormalization, abstract datatypes, and bounded exceptions.
+- The construction-path audit, trusted-compiler-gap record, effect-order check,
+  repository compatibility paths, and language-neutral assertion taxonomy are
+  Developer adaptations of that source's type-driven design argument.

package/skills/verify/SKILL.md

@@ -74,8 +74,11 @@ after code changes, new evidence, changed claims, or source-provenance changes.
 1. Extract the exact claims from the request, accepted decisions, implementation
    report, invariant, or model.
 2. Attach concrete evidence to each claim and classify its strength.
-3. Check constraints, forbidden cases, transitions, callers, and abstraction
-   stop checks when they are part of the claim.
+3. Check constraints, forbidden cases, transitions, callers, abstraction stop
+   checks, and every construction or re-entry path for invariant-carrying values
+   when they are part of the claim. Validation followed by an assertion, a
+   public raw constructor, unchecked deserialization, or a domain effect before
+   parsing is a pass-but-wrong shape, not type evidence.
 4. Distinguish verifier execution from verifier relevance.
 5. Ask what wrong implementation could still pass and name its concrete shape.
 6. Narrow any passing claim that is broader than its evidence.

package/skills/verify/references/verifier-selection-and-pass-but-wrong.md

@@ -26,7 +26,7 @@ Separate independently falsifiable claims:
 - user or caller behavior;
 - forbidden and boundary cases;
 - data multiplicity and preservation;
-- type or API contract;
+- type or API contract, including raw-to-refined construction and re-entry paths;
 - state transition and history;
 - representation or ownership boundary;
 - source/version compatibility;
@@ -102,10 +102,17 @@ calibrations by failure mechanism rather than by book.
 | database schema behavior is preserved | row content matches | labels or function-valued predicates changed | inspect schema and execute predicates/integrity checks |
 | temporal implementation is correct | each enum state is reachable | stale or duplicate event commits twice | ordered trace with stale, retry, duplicate, and concurrency |
 | abstraction is safe | public tests pass | callers still depend on fields, load order, or hidden default | leak search, fake variant, and real caller rewrite |
+| domain type carries its invariant | happy input passes and typecheck is green | validation returns no refined value, then a cast/assertion claims the domain type | inspect every construction path; require parser/smart-constructor success to return the domain value |
+| invalid input cannot affect domain state | negative parser test passes | a write, send, mutation, or partial update happens before parsing completes | effect-order integration check with invalid and partially valid input |
+| construction boundary is closed | public parser tests pass | raw constructor, ORM hydration, test factory, or legacy adapter bypasses the parser | constructor/export/re-entry search plus a direct-bypass type or runtime check |
 | package/source compatibility holds | workspace tests pass | packed artifact or installed version lacks changed files | inspect tarball/fresh install and bind provenance |
 
 A verifier for one row does not support another. In particular, location,
 residual, representation, and downstream tolerances are not interchangeable.
+A typecheck proves only that the program follows the declared types; an
+unchecked narrowing operation can make a false declaration typecheck. Pair
+compile-time evidence with construction-path and boundary evidence whenever the
+type itself is part of the claim.
 
 ## Formal And Search Result Boundaries
 
@@ -165,6 +172,10 @@ Unverified claims and residual risk:
 
 ## Source Trace
 
+- Alexis King, “Parse, don’t validate,” published November 5, 2019, for the
+  distinction between a check that discards information and a parser that
+  returns a refined value, plus the parsing-before-execution boundary. The
+  construction-path and effect-order verifier rows are Developer adaptations.
 - Hillel Wayne, *Logic for Programmers*, v0.14.0:
   Chapters 3-6 and 9-11, pp. 23-155, for logical/runtime preservation, partial
   specifications, generated properties, proof limits, bounded models, and solver