kiokuko-dsh 0.1.0

package/skills/kiokuko-single-purpose-functions/references/boundaries-and-ownership.md

@@ -0,0 +1,50 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
+
+# `code.boundary.v1` — boundaries and ownership
+
+Select this expert when a function receives data or authority from a caller, user, file, database, environment, network, parser, plugin, or another process.
+
+## Contract
+
+The public boundary accepts broad input only long enough to validate and normalize it into a narrow internal value. Reject malformed, ambiguous, oversized, unauthorized, or out-of-scope input before domain work or effects begin.
+
+Define explicitly:
+
+- what input representations are accepted;
+- whether normalization changes identity or only representation;
+- which limits prevent resource abuse;
+- which caller or principal is authorized;
+- which errors are public and stable;
+- who owns mutable collections, buffers, streams, or objects after the call.
+
+Validation must match the actual threat boundary. A TypeScript type annotation does not validate JSON. A UI constraint does not validate an HTTP request. A prior parser does not authorize the current operation.
+
+## Ownership rules
+
+- Treat caller-owned inputs as immutable by default. Copy before sorting, filtering in place, deleting keys, or retaining a mutable reference.
+- Do not return internal mutable state directly when callers could corrupt invariants.
+- Make transfer of ownership explicit for streams, handles, transactions, and buffers.
+- Avoid aliases where one layer can mutate data another layer assumes is stable.
+- Preserve original user data through validation failures unless destructive normalization is the explicit contract.
+
+## Boundary shape
+
+Prefer a thin public function that performs hostile-boundary work and then calls a constrained private core:
+
+```ts
+function parseCreateRequest(input: unknown): CreateRequest {
+  const parsed = createRequestSchema.safeParse(input);
+  if (!parsed.success) throw new PublicError('invalid_request');
+  return parsed.data;
+}
+
+function decideCreate(request: CreateRequest): CreateDecision {
+  // No unknown input remains here.
+}
+```
+
+Do not scatter the same validation across several deeper functions. Centralize public error mapping so transport, database, or parser details do not accidentally become the API.
+
+## Focused verification
+
+Test at least one valid input, each materially different rejection class, caller-input immutability, and the absence of effects after rejection. For authorization boundaries, include a counterexample that has valid shape but insufficient authority.

package/skills/kiokuko-single-purpose-functions/references/domain-and-types.md

@@ -0,0 +1,48 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
+
+# `code.domain.v1` — domain rules and narrow types
+
+Select this expert when the function decides business rules, computes values, classifies states, or moves an entity through a state machine.
+
+## Contract
+
+Domain logic should be deterministic for the same validated input. Keep clocks, randomness, persistence, network calls, environment reads, and logging outside the decision or inject their values explicitly.
+
+Model legal states and transitions directly. Prefer narrow unions, enums, tagged results, value objects, and exhaustive branches over booleans or loosely related nullable fields whose combinations can become invalid.
+
+Define:
+
+- the valid input state;
+- the exact transition or result;
+- invariants preserved before and after;
+- expected domain rejections;
+- whether the operation is total or intentionally partial.
+
+## Cohesion rules
+
+- A function may contain several steps when they implement one rule and change for the same reason.
+- Split unrelated policy decisions even if they currently share a caller.
+- Do not extract trivial wrappers that merely rename an expression without creating a useful contract.
+- Do not mix “decide what should happen” with “persist or publish it” when the decision can be represented as data.
+
+Example:
+
+```ts
+type Transition =
+  | { kind: 'advance'; next: State }
+  | { kind: 'reject'; code: 'stale_revision' | 'terminal' };
+
+function decideAdvance(current: State, expectedRevision: number): Transition {
+  if (current.revision !== expectedRevision) return { kind: 'reject', code: 'stale_revision' };
+  if (current.status === 'completed') return { kind: 'reject', code: 'terminal' };
+  return { kind: 'advance', next: { ...current, revision: current.revision + 1 } };
+}
+```
+
+## Failure behavior
+
+Expected domain failure is part of the result contract, not an accident to catch broadly. Use one explicit representation consistently. Reserve unexpected exceptions for integrity failures or defects that the current function cannot safely classify.
+
+## Focused verification
+
+Test representative valid states, every legal transition family, forbidden transitions, boundary values, and determinism. When a state space is finite, test exhaustiveness or generate a transition table rather than relying only on happy-path examples.

package/skills/kiokuko-single-purpose-functions/references/effects-and-data.md

@@ -0,0 +1,43 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
+
+# `code.effects.v1` — effects, data, and resource lifetime
+
+Select this expert when a contract touches a database, filesystem, network, subprocess, cache, message bus, clock, random source, UI runtime, or long-lived resource.
+
+## Contract
+
+Make the effect profile visible at the function boundary. A function that appears pure but reads global state, mutates a cache, logs sensitive data, or launches background work has a misleading contract.
+
+Separate four concerns when practical:
+
+1. validate and authorize the request;
+2. decide the domain change;
+3. apply effects under an explicit atomicity policy;
+4. translate infrastructure outcomes into the public result.
+
+Do not split a transaction merely to make functions shorter. Operations that must commit or roll back together belong under one transaction owner. Conversely, do not hide unrelated writes inside a function whose name promises only a read or calculation.
+
+## Data integrity
+
+- State which writes are atomic and which partial outcomes are possible.
+- Use compare-and-set, revision checks, unique constraints, or locks where concurrent writers can violate invariants.
+- Check affected-row counts when they prove the intended state transition occurred.
+- Never claim persistence before durable completion.
+- Keep schema or serialization compatibility explicit at stored-data boundaries.
+- Do not swallow a failed cleanup, rollback, or close when it changes correctness.
+
+## External effects
+
+- Bound time, output, memory, and retries.
+- Define cancellation semantics: cancelling the UI is not the same as cancelling the work.
+- Close files, streams, transactions, child processes, and subscriptions on success and failure.
+- Avoid fire-and-forget work unless ownership, failure reporting, and process lifetime are deliberately defined.
+- Sanitize logs and previews; do not leak secrets or private payloads through diagnostic output.
+
+## Testing seam
+
+Inject the narrow effect capability needed by the contract rather than an entire ambient service container. A focused fake should let tests observe calls, order, arguments, cleanup, and failure mapping without reproducing the infrastructure implementation.
+
+## Focused verification
+
+Test successful effect order, failure before mutation, failure during mutation, rollback or cleanup, timeout/cancellation, and concurrent or stale writes when applicable. Integration-test the real adapter separately from deterministic domain tests.

package/skills/kiokuko-single-purpose-functions/references/kiokuko-patterns.md

@@ -0,0 +1,344 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
+
+# Single-purpose implementation patterns
+
+These patterns are repository- and language-agnostic contracts illustrated with TypeScript for concreteness. Translate them into the project’s language, framework, error model, persistence layer, and test tools. Reuse existing project helpers before creating substitutes.
+
+## 1. Hostile boundary, constrained private core
+
+An exported operation may accept unconstrained input when it is the real trust boundary. Validate once, create an owned value, then call a constrained helper.
+
+```ts
+interface ValidatedWindow {
+  readonly start: number;
+  readonly limit: number;
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function parseWindow(value: unknown): ValidatedWindow {
+  if (!isPlainRecord(value)) throw new Error('window must be an object');
+  if (typeof value.start !== 'number' || !Number.isInteger(value.start) || value.start < 0) {
+    throw new Error('window start is invalid');
+  }
+  if (typeof value.limit !== 'number' || !Number.isInteger(value.limit)
+    || value.limit < 1 || value.limit > 100) {
+    throw new Error('window limit is invalid');
+  }
+  return { start: value.start, limit: value.limit };
+}
+
+function calculateEnd(window: ValidatedWindow): number {
+  return window.start + window.limit;
+}
+
+export function endOfWindow(value: unknown): number {
+  return calculateEnd(parseWindow(value));
+}
+```
+
+Use the project’s error type and validation library where available. Do not make `calculateEnd` accept `unknown` or repeat transport validation throughout the domain.
+
+## 2. Closed schema at a request boundary
+
+Use bounded schemas and reject unknown fields when the protocol is closed.
+
+```ts
+import * as z from 'zod/v4';
+
+const requestSchema = z.object({
+  requestId: z.string().trim().min(1).max(256),
+  paths: z.array(z.string().trim().min(1).max(1_024)).max(100),
+  limit: z.number().int().min(1).max(100).default(20),
+}).strict();
+```
+
+A schema is the boundary. Internal helpers should consume its validated output or a narrower domain value.
+
+## 3. Exact optional values
+
+Omit absent optional properties rather than assigning ambiguous placeholders.
+
+```ts
+interface Candidate {
+  readonly id: string;
+  readonly description?: string;
+}
+
+function candidate(id: string, description: string | undefined): Candidate {
+  return {
+    id,
+    ...(description === undefined ? {} : { description }),
+  };
+}
+```
+
+Use the equivalent convention in languages that distinguish missing, null, and empty values.
+
+## 4. Immutable transformation and mutation test
+
+```ts
+interface Profile {
+  readonly mode: 'build' | 'debug' | null;
+  readonly target: string | null;
+}
+
+function withTarget(profile: Profile, target: string): Profile {
+  return { ...profile, target: target.trim() };
+}
+```
+
+```ts
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+test('returns a new profile without mutating the input', () => {
+  const input = { mode: 'build' as const, target: null };
+  const before = structuredClone(input);
+
+  const result = withTarget(input, ' src/index.ts ');
+
+  assert.deepEqual(result, { mode: 'build', target: 'src/index.ts' });
+  assert.deepEqual(input, before);
+  assert.notEqual(result, input);
+});
+```
+
+## 5. Explicit variable dependencies
+
+Keep time and randomness out of pure ranking, hashing, transition, and validation functions.
+
+```ts
+interface Dependencies {
+  readonly now: () => string;
+  readonly createId: () => string;
+}
+
+interface CreatedRecord {
+  readonly id: string;
+  readonly createdAt: string;
+}
+
+function createRecord(dependencies: Dependencies): CreatedRecord {
+  return {
+    id: dependencies.createId(),
+    createdAt: dependencies.now(),
+  };
+}
+```
+
+Production composition supplies real dependencies; tests supply deterministic ones.
+
+## 6. Transaction-agnostic store, transaction-owning use case
+
+The store performs persistence. The service or use case owns the atomic operation.
+
+```ts
+interface Transaction {
+  execute(sql: string, parameters: readonly unknown[]): void;
+}
+
+interface NewItem {
+  readonly id: string;
+  readonly value: string;
+}
+
+function insertItem(transaction: Transaction, item: NewItem): void {
+  transaction.execute(
+    'INSERT INTO items (id, value) VALUES (?, ?)',
+    [item.id, item.value],
+  );
+}
+
+function createItem(
+  runTransaction: (operation: (transaction: Transaction) => void) => void,
+  item: NewItem,
+): void {
+  runTransaction((transaction) => {
+    insertItem(transaction, item);
+    transaction.execute(
+      'INSERT INTO audit_events (event_type, target_id) VALUES (?, ?)',
+      ['item_created', item.id],
+    );
+  });
+}
+```
+
+Do not let `insertItem` start its own transaction if it must compose with other writes. Do not call a provider or perform unrelated slow I/O inside the transaction.
+
+## 7. Validate stored data before domain use
+
+Driver types and generated models are not always runtime proof, especially across migrations or external storage.
+
+```ts
+interface StoredItem {
+  readonly id: string;
+  readonly revision: number;
+}
+
+function parseStoredItem(row: Record<string, unknown> | undefined): StoredItem {
+  if (row === undefined) throw new Error('Item not found');
+  if (typeof row.id !== 'string'
+    || typeof row.revision !== 'number'
+    || !Number.isInteger(row.revision)
+    || row.revision < 1) {
+    throw new Error('Stored item is invalid');
+  }
+  return { id: row.id, revision: row.revision };
+}
+```
+
+Do not include malformed row contents in a public error.
+
+## 8. Safe public error mapping
+
+Public messages should be stable. Keep only allowlisted bounded details.
+
+```ts
+interface PublicFailure {
+  readonly code: 'busy' | 'invalid' | 'internal';
+  readonly message: string;
+  readonly retryAfterSeconds?: number;
+}
+
+function publicFailure(error: unknown): PublicFailure {
+  if (isBusyFailure(error)) {
+    return {
+      code: 'busy',
+      message: 'Service is busy',
+      retryAfterSeconds: clampRetryDelay(error.retryAfterSeconds),
+    };
+  }
+  if (isValidationFailure(error)) {
+    return { code: 'invalid', message: 'Request is invalid' };
+  }
+  return { code: 'internal', message: 'Internal error' };
+}
+```
+
+Do not copy unknown exception messages, submitted values, credentials, URLs with secret query parameters, or provider bodies into public output.
+
+## 9. Preserve operation and cleanup failures
+
+When both fail, retain both failures without replacing the primary one.
+
+```ts
+async function useResource<T>(
+  open: () => Promise<{ close: () => Promise<void> }>,
+  operation: (resource: { close: () => Promise<void> }) => Promise<T>,
+): Promise<T> {
+  const resource = await open();
+  let operationFailure: unknown;
+  let result: { value: T } | undefined;
+
+  try {
+    result = { value: await operation(resource) };
+  } catch (error) {
+    operationFailure = error;
+  }
+
+  try {
+    await resource.close();
+  } catch (cleanupFailure) {
+    if (operationFailure !== undefined) {
+      throw new AggregateError(
+        [operationFailure, cleanupFailure],
+        'Resource operation and cleanup failed',
+      );
+    }
+    throw cleanupFailure;
+  }
+
+  if (operationFailure !== undefined) throw operationFailure;
+  if (result === undefined) throw new Error('Resource operation produced no result');
+  return result.value;
+}
+```
+
+Use the language’s structured multi-error or error-chaining mechanism where possible.
+
+## 10. Classify failures by structured fields
+
+Prefer error types, codes, status values, or discriminated variants over message matching.
+
+```ts
+interface RetryableFailure extends Error {
+  readonly code: 'temporarily_unavailable';
+  readonly retryAfterSeconds: number;
+}
+
+function isRetryableFailure(error: unknown): error is RetryableFailure {
+  return error instanceof Error
+    && 'code' in error
+    && error.code === 'temporarily_unavailable'
+    && 'retryAfterSeconds' in error
+    && typeof error.retryAfterSeconds === 'number';
+}
+```
+
+Do not treat an unrelated exception containing “busy” or “timeout” as retryable.
+
+## 11. Immutable replay identity
+
+Bind every field that changes the meaning of an idempotent operation.
+
+```ts
+interface BoundRequest {
+  readonly operation: string;
+  readonly subjectId: string;
+  readonly expectedRevision: number;
+  readonly mode: 'validate' | 'apply';
+}
+
+function replayMatches(left: BoundRequest, right: BoundRequest): boolean {
+  return left.operation === right.operation
+    && left.subjectId === right.subjectId
+    && left.expectedRevision === right.expectedRevision
+    && left.mode === right.mode;
+}
+```
+
+Reusing an identity with changed bound input is a conflict, not a second mutation.
+
+## 12. Compare-and-swap filesystem changes
+
+For managed files, the contract may include expected content, expected file identity, expected parent-directory identity, alternate paths that must remain absent, restrictive mode, reverse-order rollback, and explicit ambiguous-cleanup failure.
+
+Use the project’s atomic compare-and-swap helpers where available. Plain write, rename, or delete calls are insufficient when concurrent changes or independently owned files must be protected.
+
+## 13. Test secret non-echo
+
+```ts
+test('rejects invalid input without echoing it', () => {
+  const submitted = 'secret-sentinel-value';
+
+  assert.throws(
+    () => parseWindow({ start: submitted, limit: 10 }),
+    (error: unknown) => {
+      assert.ok(error instanceof Error);
+      assert.equal(error.message.includes(submitted), false);
+      return true;
+    },
+  );
+});
+```
+
+## 14. Test deterministic output
+
+For canonical order, hashes, manifests, and rankings, construct semantically equivalent inputs with different insertion order and assert identical output.
+
+## 15. Verification sequence
+
+Run commands that actually exist in the repository:
+
+1. the narrowest test covering the changed contract;
+2. relevant integration tests;
+3. type or static checks;
+4. the broader test suite when shared behavior changed;
+5. build and package checks when distribution changed.
+
+Report skipped commands and failures exactly. Do not invent a lint, formatter, build, or test command that the project does not define.

package/skills/kiokuko-single-purpose-functions/references/problem-shaping-and-language.md

@@ -0,0 +1,84 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
+
+# `code.modeling.v1` — problem shaping and representation design
+
+Select this expert when a contract defines a public data shape, introduces
+domain vocabulary, or translates between human intent, domain values, storage,
+transport, serialization, and consumer or UI representations.
+
+Do not select it for a representation-preserving mechanical change merely
+because the work modifies code. This expert does not require Lisp syntax, a
+Lisp runtime, macros, a DSL, or a separate design document.
+
+## Contract
+
+Turn the human problem into named concepts and explicit transformations before
+letting a database schema, ORM model, framework object, wire format, or UI state
+become the accidental product contract.
+
+For a non-trivial selected contract, make these items explicit in the working
+plan or review notes, without creating a new artifact unless the user asks:
+
+1. **Intent:** identify the actor, their goal, the observable result, and data
+   that must remain hidden or out of scope.
+2. **Representation map:** list only the layers that actually exist, using this
+   shape as a guide: `human intent -> domain concept -> storage/input shape ->
+   public shape -> consumer shape`.
+3. **Consumer-first shape:** define what the external caller or next layer
+   needs before choosing how to retrieve, serialize, or display it.
+4. **Named transformations:** use names that reveal the concept and direction,
+   such as `rowToArticle`, `articleToApiResponse`, or
+   `apiResponseToArticleViewState`.
+5. **Loss and failure policy:** state what is omitted, normalized, derived,
+   rejected, or intentionally impossible to reconstruct at each boundary.
+6. **Abstraction threshold:** start with direct values and cohesive functions.
+   Extract shared vocabulary after meaningful repetition appears; introduce a
+   DSL, macro, code generator, or generic framework only when the stable pattern
+   and its benefit are evidenced.
+
+## Representation boundaries
+
+- Storage shapes serve persistence and query needs; they are not automatically
+  domain or public shapes.
+- Domain shapes name legal concepts and invariants without inheriting transport
+  or framework accidents.
+- Public API and event shapes are compatibility and disclosure contracts. Build
+  them from allowlisted fields rather than serializing internal objects.
+- Consumer and UI shapes serve rendering and interaction state. Do not force
+  components to understand database relations or transport-only nullability.
+- Use distinct shapes for distinct audiences when list, detail, administrative,
+  and public views carry different concepts or disclosure rules.
+
+Pair this expert with `code.boundary.v1` when the transformation crosses an
+untrusted or public boundary. Pair it with `code.domain.v1` when the named shape
+owns business states, invariants, or transitions. Stay within the three-expert
+limit and select only risks owned by the same cohesive contract.
+
+## Failure modes
+
+- Returning an ORM entity, database row, or framework object directly as a
+  public response.
+- Treating storage column names or relations as a stable external API by
+  accident.
+- Reusing one DTO for audiences whose visibility or interaction needs differ.
+- Mixing server response state, domain state, and UI state in one mutable type.
+- Adding wrappers that rename syntax but create no semantic contract.
+- Generalizing one instance into a DSL or metaprogramming layer before stable
+  repetition exists.
+
+## Focused verification
+
+Test the observable shape and transformation rather than the current storage or
+framework implementation:
+
+- assert the exact allowed public fields and the absence of internal or secret
+  fields;
+- cover missing, optional, normalized, derived, and rejected values;
+- verify intentional information loss or round-trip behavior where relevant;
+- prove that a storage-layout or transport-fixture change does not silently
+  redefine the public concept;
+- test audience-specific shapes independently when their contracts differ.
+
+This guidance adapts the problem-shaping philosophy described in
+<https://zenn.dev/circleback/articles/what-is-lisp>; it applies that philosophy
+across programming languages and does not reproduce the article text.

package/skills/kiokuko-single-purpose-functions/references/protocols-and-idempotency.md

@@ -0,0 +1,42 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
+
+# `code.protocol.v1` — protocols, concurrency, and idempotency
+
+Select this expert when callers retry, messages can be duplicated, state is revisioned, several actors race, or a public/API/storage protocol must remain compatible.
+
+## Contract
+
+Identity, ordering, and state transition rules are public behavior. Do not infer them from error text, timestamps, repository-wide “latest” records, or other ambiguous signals.
+
+Define:
+
+- the stable operation or request identity;
+- which input fields are bound to that identity;
+- the exact legal source states;
+- the expected revision or version;
+- retry and replay behavior;
+- what a duplicate with identical input returns;
+- what a duplicate identity with changed input returns;
+- which actor owns each transition.
+
+## Idempotency
+
+A safe idempotent operation distinguishes exact replay from conflicting reuse. Persist or derive a digest from the complete bound input. Return the stored result for an exact replay; reject changed input under the same key.
+
+Do not generate a new identity for a transport retry. Do generate a new identity for a new logical operation, even when the visible task text happens to match.
+
+## Concurrency
+
+- Check revision and allowed source state in the same atomic mutation.
+- Make ambiguous candidates fail closed or remain unbound; never guess.
+- Treat zero or multiple affected rows as evidence that the expected transition did not occur.
+- Prevent stale completion, retry, or callback results from overwriting newer state.
+- Keep terminal states terminal unless the protocol explicitly defines a new revision or recovery transition.
+
+## Compatibility
+
+For versioned APIs or stored structures, accept an older representation only when the compatibility policy is explicit and tested. Do not create silent fallback paths that bypass a new safety invariant. Prefer a clean break when old data cannot satisfy the current contract safely.
+
+## Focused verification
+
+Test first execution, exact replay, conflicting reuse, stale revision, wrong source state, concurrent claim, terminal-state behavior, and response compatibility. A text-match test is insufficient when the protocol exposes structured codes or exact identities.