@hobin/developer 0.1.8 → 0.1.10

package/skills/sketch/references/abstraction-composition-and-state.md

@@ -1,184 +0,0 @@
-# Abstraction, Composition, And State
-
-Use this reference when a sketch must choose a level of language, hide a
-representation, compose reusable units, expose the process a procedure creates,
-or place history. The core insight is not “add an abstraction.” It is:
-
-> Let each level speak only through the vocabulary immediately below it, so a
-> representation, process, or state choice can change without forcing every
-> caller to change.
-
-An abstraction is real only when it hides a consequential choice and leaves a
-smaller, truthful contract.
-
-## Complete Example: A Representation Barrier
-
-Requirement: calculate and display the duration of a schedule while accepting
-several storage formats.
-
-### Wishful use
-
-```text
-label(schedule) = formatDuration(duration(schedule))
-```
-
-The top level speaks about schedules and durations, not tuples, JSON keys, or
-date-library objects.
-
-### Public vocabulary and law
-
-```text
-makeSchedule(start, end, timezone) -> Schedule
-startOf(schedule)                  -> Instant
-endOf(schedule)                    -> Instant
-timezoneOf(schedule)               -> Timezone
-
-law: endOf(makeSchedule(s, e, z)) == e
-law: startOf(makeSchedule(s, e, z)) == s
-invariant: e is not earlier than s
-```
-
-### Two representations
-
-```text
-Representation A: { start, end, timezone }
-Representation B: [timezone, epochStart, epochEnd]
-```
-
-`duration` is written only with `startOf` and `endOf`. Switching A to B should
-change constructors/selectors and boundary adapters, not `duration` or `label`.
-That replacement test is what makes the barrier concrete. A `Schedule` type
-whose callers still read `.epochEnd` is only a new name for a leaked
-representation.
-
-### Where policy lives
-
-Validation and normalization belong to the constructor or an explicit external
-adapter. The selectors do not invent fallback timezones. If callers need raw
-source distinctions, the barrier must preserve them or expose a separate source
-view; normalization is a loss of ability as well as a gain in guarantees.
-
-## Three-Level Sketch
-
-For consequential designs, write the levels explicitly:
-
-```text
-product level:
-  label, reschedule, overlaps
-
-domain representation level:
-  makeSchedule, startOf, endOf, timezoneOf
-
-mechanism level:
-  JSON fields, database columns, date-library values
-```
-
-Check every dependency arrow. Product operations may use the domain vocabulary;
-only the representation owner may use mechanism details. Add another level only
-when it introduces meaningful primitives, combinations, or reusable names.
-
-## Select The Specific Reference
-
-| Unresolved question | Read | Required output |
-| --- | --- | --- |
-| wished top level, representation barrier, higher-order unit, closure, or conventional interface | [Abstraction Barriers And Closure](abstraction-barriers-and-closure.md) | level map, public operations/laws, hidden representation, replacement and closure checks |
-| process shape, cost, state/history, identity, concurrency, streams, or event order | [Processes, State, And Time](processes-state-and-time.md) | process trace/cost or explicit history owner and ordering law |
-| multiple representations, generic operations, registration, symbolic data, DSL, evaluator, or runtime boundary | [Generic Operations And Languages](generic-operations-and-languages.md) | variant-operation matrix or language vocabulary plus evaluator contract |
-
-Read [Responsibility And Variation](responsibility-and-variation.md) instead when
-the main question is who should own knowledge, collaboration, creation, or a
-changing role.
-
-## Modules As Models
-
-A module is a useful model of an environment, not merely a folder. Fill:
-
-```text
-environment: real context and change pressure
-model: represented facets and deliberately ignored facts
-interface: sense exposed to users
-assumptions: environmental facts required for the model to remain useful
-```
-
-Example:
-
-```text
-module: ExchangeRateQuote
-environment: provider responses, currencies, timestamps, outages
-model: base, quote, rate, observedAt
-ignored: provider request IDs and transport headers
-interface: convert(amount), age(now)
-assumptions: rate is positive; observedAt uses a comparable clock
-```
-
-If a caller needs provider headers to decide freshness, either freshness is
-owned by the wrong layer or the model omitted a required fact.
-
-A coherent **principled component** may share assumptions internally and use
-weak indirection. An **adaptable system** needs stronger interfaces between
-components with different assumptions or replacement pressure. Do not impose
-plugin-style indirection inside every cohesive unit, and do not expose internals
-between independently evolving units.
-
-## Pull, Transform, Push
-
-Many processes can be sketched as:
-
-```text
-pull: acquire and validate external information
-transform: compute a context-light domain result
-push: interpret effects or update the environment
-```
-
-Example:
-
-```text
-pullOrders() -> Orders
-planNotifications(Orders) -> List<Notification>
-sendNotifications(List<Notification>) -> DeliveryReport
-```
-
-This split is useful when failures, retries, and tests differ by phase. Reject it
-when one atomic transaction or shared-state invariant is the actual product
-boundary.
-
-## Sketch Output
-
-```text
-Top level: product operations written wishfully
-Levels: vocabulary and allowed dependency direction
-Barrier: public operations/laws, hidden choice, invariant owner
-Replacement: alternative implementation that should leave callers unchanged
-Composition: primitives, combinators, closure boundary, finalizers
-Process: generated work, cost, time, failure, and ordering
-Module: environment, model, interface, assumptions
-State: history owner or explicit stream/log
-Checks: leak, replacement, closure, trace, and order evidence
-```
-
-## Failure Diagnosis
-
-| Symptom | Return to |
-| --- | --- |
-| wished function merely renames a mechanism | product vocabulary and hidden choice |
-| callers assemble or inspect raw representation | barrier operations and leak check |
-| composed result cannot be combined again | closure boundary and finalizer split |
-| short code creates unexplained stack/buffer/order cost | process trace |
-| module boundary follows directories only | environment/model/interface/assumptions |
-| same call changes after prior interactions | history placement |
-| new variant edits every old package | generic operation axes |
-| configuration syntax has no evaluator/error semantics | ordinary data/functions or language contract |
-
-## Source Trace
-
-- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
-  Interpretation of Computer Programs*, Second Edition, MIT Press, 1996:
-  black-box abstraction, data-abstraction barriers, closure, conventional
-  interfaces, procedure/process distinction, generic operations, state,
-  streams, and metalinguistic abstraction.
-- Zachary Tellman, *Elements of Clojure*, 2019: modules as models,
-  environment/model/interface/assumptions, principled versus adaptable systems,
-  units of computation, and process construction.
-- Hillel Wayne, *Logic for Programmers*, version 0.14.0, May 4, 2026:
-  ability-guarantee tradeoffs and the separation of mathematical models from
-  runtime semantics.

package/skills/sketch/references/composition-generative-recursion-and-accumulators.md

@@ -1,196 +0,0 @@
-# Composition, Generative Recursion, And Accumulators
-
-Use this reference after the base data recipe when structure alone does not
-finish the design. It distinguishes four moves that are often blurred together:
-designing an auxiliary, abstracting completed designs, generating new
-subproblems, and remembering knowledge that traversal would otherwise lose.
-
-## Design By Composition
-
-Write a wishful top level before helper bodies:
-
-```text
-publishableTasks(tasks):
-  return sortByPriority(onlyReady(normalize(tasks)))
-```
-
-For each wished operation, run the full small recipe:
-
-```text
-purpose: what subproblem it solves
-contract: input and output meanings
-examples: representative success and boundary cases
-template: derived from its data
-reason: why it is a distinct subproblem
-```
-
-An auxiliary is earned when it solves a separate domain subproblem, processes a
-referenced data definition, or generalizes a problem that the direct design
-exposes. “The original function is long” is not an independent purpose.
-
-## Abstraction From Completed Examples
-
-Start with at least two correct concrete designs that share a template.
-
-```text
-sum(numbers):
-  Empty -> 0
-  Node(first, rest) -> first + sum(rest)
-
-allReady(tasks):
-  Empty -> true
-  Node(first, rest) -> first.ready && allReady(rest)
-```
-
-Align corresponding positions:
-
-| Role | `sum` | `allReady` |
-| --- | --- | --- |
-| base | `0` | `true` |
-| item projection | identity | `task.ready` |
-| combine | `+` | `&&` |
-
-Only now is a fold-shaped candidate visible:
-
-```text
-fold(sequence, base, project, combine)
-```
-
-The shared template is evidence, not approval. Check that the roles have stable
-meaning, old functions become simple calls, process/cost does not accidentally
-change, and one realistic new case fits without adding flags. `abstraction-review`
-owns the promotion decision.
-
-## Structural Versus Generative Recursion
-
-Structural recursion consumes pieces selected directly from the input data
-definition. Generative recursion creates a new problem by domain knowledge.
-
-```text
-structural: totalEstimate(rest)
-  // rest is a field in Node(Task, Tasks)
-
-generative: binarySearch(sorted, lower, midpoint - 1)
-  // the next interval is calculated, not selected from a data field
-```
-
-Misclassifying the second as structural hides the algorithm idea and its
-termination obligation.
-
-## Generative Recursion Recipe
-
-Answer four questions before the body:
-
-```text
-trivial: which problems have a direct answer?
-generate: how are new subproblems produced?
-solve/combine: how do recursive answers form this answer?
-terminate: why do generated problems approach a trivial case?
-```
-
-Worked binary-search sketch:
-
-```text
-search(sorted, target, low, high):
-  if low > high:
-    return NotFound                    // trivial
-
-  mid = floor((low + high) / 2)        // generation knowledge
-  if sorted[mid] == target:
-    return Found(mid)                  // trivial
-  if target < sorted[mid]:
-    return search(sorted, target, low, mid - 1)
-  return search(sorted, target, mid + 1, high)
-```
-
-Process examples must show generated intervals:
-
-```text
-[0, 6] -> [4, 6] -> [4, 4] -> Found(4)
-[0, 0] -> [1, 0] -> NotFound
-```
-
-Termination measure: `high - low + 1` is a natural number for non-trivial
-calls, and each recursive call strictly decreases it. If no decreasing measure
-is known, state the possible non-termination boundary rather than asserting
-that the input “gets smaller.”
-
-## Accumulator Recipe
-
-Do not begin by adding an extra parameter. First identify the lost knowledge or
-repeated work in a conventional design.
-
-Example pressure: repeatedly appending to the end while reversing a sequence
-reprocesses prior results. Introduce `seenReversed` with an invariant:
-
-```text
-original == reverse(seenReversed) ++ remaining
-```
-
-Trace the relation:
-
-```text
-original [a,b,c], remaining [a,b,c], seenReversed []
-original [a,b,c], remaining [b,c],   seenReversed [a]
-original [a,b,c], remaining [c],     seenReversed [b,a]
-original [a,b,c], remaining [],      seenReversed [c,b,a]
-```
-
-The invariant determines initialization, update, and result:
-
-```text
-reverse(items):
-  loop(remaining, seenReversed):
-    Empty -> seenReversed
-    Node(first, rest) -> loop(rest, prepend(first, seenReversed))
-  return loop(items, Empty)
-```
-
-Check the invariant at three points:
-
-1. initialization relates the original input to the initial accumulator;
-2. one transition preserves the relationship;
-3. the base case plus the invariant implies the promised result.
-
-Different invariants create different algorithms. Choose the simplest invariant
-that solves observed pressure; an accumulator with no stated meaning is hidden
-state.
-
-## Iterative Refinement
-
-When a required case cannot be expressed or a forbidden case remains possible,
-change the data definition and propagate the change through:
-
-```text
-data examples
--> behavior examples
--> templates
--> implementations
--> tests
--> serialized/public compatibility surfaces
-```
-
-A local type edit is incomplete when old persisted forms or callers remain in
-circulation.
-
-## Failure Diagnosis
-
-| Symptom | Repair |
-| --- | --- |
-| wished helper has no examples or independent purpose | inline it or run its own recipe |
-| abstraction is derived from one function | complete another concrete design first |
-| abstract parameters are implementation fragments | restate stable variation roles |
-| generated recursive call lacks an algorithm idea | return to structural template or state generation rule |
-| termination says only “smaller” | provide a well-founded measure or explicit divergence boundary |
-| accumulator is added for style | show lost knowledge, repeated work, or process pressure |
-| accumulator update is guessed | derive it from the invariant |
-
-## Source Trace
-
-- [*How to Design Programs*, official living edition](https://htdp.org/2026-5-28/Book/index.html):
-  design by composition, abstraction from concrete functions, generative
-  recursion and termination, accumulators and invariants, and iterative
-  refinement.
-- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
-  Interpretation of Computer Programs*, Second Edition, MIT Press, 1996:
-  wishful procedure decomposition, higher-order abstraction, and process shape.

package/skills/sketch/references/generic-operations-and-languages.md

@@ -1,134 +0,0 @@
-# Generic Operations And Languages
-
-Use this reference when several representations must coexist additively, or
-when ordinary data and functions are becoming a small language with its own
-evaluation semantics.
-
-## Two Axes Of Generic Operations
-
-Write the matrix before choosing classes, visitors, multimethods, or a registry:
-
-| Representation | `charge` | `refund` | `describe` |
-| --- | --- | --- | --- |
-| Card | method | method | method |
-| Bank transfer | method | unsupported | method |
-| Store credit | method | method | method |
-
-There are two independent pressures:
-
-- horizontal: higher-level operations should not know representation fields;
-- vertical: adding a representation should not require editing every old
-  representation package.
-
-One possible data-directed surface is:
-
-```text
-register(kind, operation, method)
-applyGeneric(operation, taggedValue, ...args)
-```
-
-Specify duplicate registration, missing method, load order, type transitions,
-and error visibility. Then add a fake representation. Existing callers and old
-representation modules should remain unchanged. If only two stable variants
-exist, a local conditional may be cheaper and clearer.
-
-## Coercion And Meaning Preservation
-
-For mixed representations, draw paths:
-
-```text
-Integer -> Rational -> Decimal
-Money(USD) -X-> Money(EUR) without an exchange-rate context
-```
-
-For each edge state preserved meaning and lost ability: precision, identity,
-order, metadata, or capability. Choose direct operation, coercion, canonical
-representation, or explicit rejection. A convenient path that silently loses
-meaning is not genericity.
-
-## Symbolic Data Boundary
-
-When code inspects formulas, queries, or rules, represent notation as data:
-
-```text
-Expr = Number(value) | Variable(name) | Sum(left, right) | Product(left, right)
-```
-
-Algorithms use predicates/selectors/constructors or pattern matching on this
-semantic definition, not string indexes. Constructors may own simplification:
-
-```text
-makeSum(0, x) -> x
-makeSum(x, 0) -> x
-makeSum(x, y) -> Sum(x, y)
-```
-
-That policy must be explicit because it changes the representation while
-preserving intended expression meaning.
-
-## When Data Becomes A Language
-
-A rule table, query builder, workflow schema, or configuration is a language
-only when it has:
-
-```text
-primitives: smallest valid expressions
-combination: how expressions form larger expressions
-abstraction: how recurring expressions receive reusable names
-validation: well-formed versus invalid programs
-evaluation: what an expression means in an environment
-errors: parse, validation, runtime, and unsupported behavior
-evolution: versioning, migrations, and compatibility
-```
-
-Worked policy DSL sketch:
-
-```text
-Policy = Allow(Role) | HasTag(Tag) | All(List<Policy>) | Any(List<Policy>)
-
-evaluate(Allow("admin"), env) = env.user.role == "admin"
-evaluate(All([]), env) = true
-evaluate(All([p, ...rest]), env) = evaluate(p, env) && evaluate(All(rest), env)
-```
-
-Define invalid states, such as an unknown role or empty `Any`, rather than
-letting a host-language exception become language semantics.
-
-## Evaluator Boundary
-
-Keep the evaluator contract distinct from syntax:
-
-```text
-evaluate : Program x Environment -> Result | LanguageError
-```
-
-State evaluation order, scope, effects, termination limits, and resource
-budgets. A mathematically equivalent rewrite may not preserve host-language
-short-circuiting, effects, or exceptions.
-
-Do not build a DSL when ordinary typed data plus functions keep policy more
-visible. The evaluator, migrations, debugging tools, and error messages are
-product code, not free infrastructure.
-
-## Artifact
-
-```text
-Variant-operation matrix:
-Representation barrier:
-Registration/dispatch and unsupported policy:
-Conversion graph and preserved meaning:
-Language primitives/combinations/abstractions:
-Validation and evaluator contract:
-Errors, effects, versioning, and limits:
-Fake variant or example program check:
-Simpler ordinary-data alternative:
-```
-
-## Source Trace
-
-- *Structure and Interpretation of Computer Programs*, Second Edition,
-  sections 2.4-2.5 and chapters 4-5: multiple representations, generic
-  operations, data-directed programming, symbolic data, metalinguistic
-  abstraction, evaluators, and explicit machines.
-- Hillel Wayne, *Logic for Programmers*, version 0.14.0, May 4, 2026:
-  model/runtime distinctions and ability-guarantee tradeoffs.

package/skills/sketch/references/processes-state-and-time.md

@@ -1,171 +0,0 @@
-# Processes, State, And Time
-
-Use this reference when returned values alone do not describe correctness. The
-same procedure text can generate recursive, iterative, tree-shaped, delayed, or
-stateful processes with different time, space, order, and failure behavior.
-
-## Procedure Versus Process
-
-Trace a representative execution:
-
-```text
-procedure: retry(operation, 3)
-process:
-  attempt 1 -> retryable failure -> wait 100 ms
-  attempt 2 -> retryable failure -> wait 200 ms
-  attempt 3 -> success
-```
-
-Record:
-
-```text
-result
-work generated at each step
-deferred work or stack growth
-state retained or duplicated
-time/space scale
-ordering and failure surface
-```
-
-A recursive tree walk and an iterative queue walk may return the same nodes but
-have different stack, ordering, and memory contracts. A fluent one-line pipeline
-may materialize three full collections. Short procedure text is not evidence of
-a cheap or simple process.
-
-## State Means History Matters
-
-Compare two calls with identical explicit input:
-
-```text
-account.withdraw(40) -> Accepted
-account.withdraw(40) -> Rejected
-```
-
-If prior interactions explain the difference, state is part of the contract.
-Fill:
-
-```text
-required history: accepted deposits and withdrawals
-sufficient summary: current balance
-owner: account instance
-writers: deposit and withdraw
-identity: two equal balances may be different accounts
-aliases: references that observe the same mutation
-order law: sufficient-funds check and balance update are one transition
-```
-
-Local state is modular when it hides a coherent history behind a small
-interface. It is hazardous when aliases, retries, concurrency, or persistence
-make the history owner unclear.
-
-## Explicit State Machine Alternative
-
-Represent time as data when transitions need review, replay, or distribution:
-
-```text
-Payment = Created | Authorizing(attempt) | Authorized(id) | Failed(reason)
-
-transition(Created, Authorize) -> Authorizing(1)
-transition(Authorizing(n), Retryable) -> Authorizing(n + 1)
-transition(Authorizing(_), Approved(id)) -> Authorized(id)
-transition(Authorized(_), Approved(_)) -> invalid or idempotent policy
-```
-
-State the unchanged part of each transition and cover stale, duplicate,
-reordered, retried, and concurrent events. A correct enum is not a correct
-history model.
-
-## Event Order And Atomicity
-
-For concurrent withdrawal, the forbidden interleaving is:
-
-```text
-A reads 100
-B reads 100
-A writes 20 after withdrawing 80
-B writes 20 after withdrawing 80
-```
-
-Both calls appear accepted although 160 was withdrawn. The order law is not
-“serialize everything”; it is:
-
-```text
-read balance -> check funds -> write next balance
-```
-
-must behave as one protected transition for a given account. Choose a lock,
-transaction, queue, compare-and-swap loop, or merge policy only after stating
-that law and its waiting/fairness cost.
-
-## Streams And Logs
-
-An explicit stream/log represents successive states or events:
-
-```text
-events -> fold(transition, initialState) -> currentState
-```
-
-It improves replay, audit, time travel, merge reasoning, and functional
-composition. It also creates retention, ordering, identity, versioning, and
-reconstruction-cost obligations. Choose it when history is product evidence,
-not merely because mutation is unfashionable.
-
-For delayed streams also record demand:
-
-```text
-producer pace
-consumer pace
-buffer/backpressure
-single-use versus replayable
-failure and cancellation
-```
-
-## Pull, Transform, Push Process Check
-
-```text
-pull: where external time and failure enter
-transform: domain computation and its data contract
-push: effect interpretation, idempotency, and partial failure
-apex: coordinator that owns the whole process outcome
-```
-
-The separation is false when pull retries silently alter transform semantics or
-push performs an unreported partial success. Conversely, splitting one atomic
-transaction into these phases may violate the actual invariant.
-
-## Process/State Artifact
-
-```text
-Procedure promise:
-Representative process trace:
-Shape and time/space cost:
-Required history and sufficient summary:
-State or log owner and writers:
-Identity and alias behavior:
-Order/atomicity law:
-Retry, stale, duplicate, and concurrency policy:
-Alternative representation considered:
-Evidence and residual risk:
-```
-
-## Failure Diagnosis
-
-- Result tests pass but stack, buffering, or order matters: add a process-shaped
-  verifier.
-- Same call changes but no history is named: revise the state contract.
-- A state machine lists states but not events and next states: derive the
-  transition relation.
-- All work is serialized: narrow the protected order law.
-- A log is proposed without replay/audit/merge pressure: local state may be the
-  smaller honest model.
-- A pipeline stage hides effects: expose the phase or rename the process
-  honestly.
-
-## Source Trace
-
-- *Structure and Interpretation of Computer Programs*, Second Edition,
-  chapters 1 and 3: procedure/process distinction, state and assignment,
-  identity and sharing, concurrency, constraints, delayed evaluation, and
-  streams.
-- Zachary Tellman, *Elements of Clojure*, 2019: units of computation and the
-  construction of pull-transform-push processes.