modkh 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +24 -2
- package/dist/agent/bundled-skills.d.ts +13 -0
- package/dist/agent/bundled-skills.js +95 -0
- package/dist/agent/images.d.ts +10 -0
- package/dist/agent/images.js +33 -0
- package/dist/agent/loop.d.ts +56 -0
- package/dist/agent/loop.js +155 -0
- package/dist/agent/skills.d.ts +20 -0
- package/dist/agent/skills.js +169 -0
- package/dist/agent/types.d.ts +132 -0
- package/dist/agent/types.js +12 -0
- package/dist/cli/agents.d.ts +8 -0
- package/dist/cli/agents.js +12 -0
- package/dist/cli/approval.d.ts +27 -0
- package/dist/cli/approval.js +62 -0
- package/dist/cli/catalog.d.ts +39 -0
- package/dist/cli/catalog.js +76 -0
- package/dist/cli/chat.d.ts +18 -0
- package/dist/cli/chat.js +733 -0
- package/dist/cli/clipboard.d.ts +9 -0
- package/dist/cli/clipboard.js +54 -0
- package/dist/cli/color.d.ts +42 -0
- package/dist/cli/color.js +176 -0
- package/dist/cli/config.d.ts +41 -0
- package/dist/cli/config.js +188 -0
- package/dist/cli/editor.d.ts +16 -0
- package/dist/cli/editor.js +77 -0
- package/dist/cli/keys.d.ts +18 -0
- package/dist/cli/keys.js +82 -0
- package/dist/cli/language.d.ts +1 -0
- package/dist/cli/language.js +105 -0
- package/dist/cli/limits.d.ts +13 -0
- package/dist/cli/limits.js +19 -0
- package/dist/cli/lines.d.ts +18 -0
- package/dist/cli/lines.js +80 -0
- package/dist/cli/models.d.ts +4 -0
- package/dist/cli/models.js +69 -0
- package/dist/cli/permissions.d.ts +25 -0
- package/dist/cli/permissions.js +30 -0
- package/dist/cli/plugins.d.ts +1 -0
- package/dist/cli/plugins.js +53 -0
- package/dist/cli/providers.d.ts +46 -0
- package/dist/cli/providers.js +76 -0
- package/dist/cli/terminal.d.ts +143 -0
- package/dist/cli/terminal.js +742 -0
- package/dist/cli/usage.d.ts +29 -0
- package/dist/cli/usage.js +75 -0
- package/dist/index.d.ts +11 -0
- package/dist/index.js +164 -0
- package/dist/language/catalog.d.ts +44 -0
- package/dist/language/catalog.js +100 -0
- package/dist/language/commonlisp-bundled.d.ts +11 -0
- package/dist/language/commonlisp-bundled.js +22 -0
- package/dist/language/commonlisp-dependencies.d.ts +16 -0
- package/dist/language/commonlisp-dependencies.js +68 -0
- package/dist/language/commonlisp-install.d.ts +14 -0
- package/dist/language/commonlisp-install.js +213 -0
- package/dist/language/commonlisp-reader.d.ts +17 -0
- package/dist/language/commonlisp-reader.js +47 -0
- package/dist/language/commonlisp-systems.d.ts +3 -0
- package/dist/language/commonlisp-systems.js +32 -0
- package/dist/language/commonlisp-tls.d.ts +10 -0
- package/dist/language/commonlisp-tls.js +51 -0
- package/dist/language/detect.d.ts +29 -0
- package/dist/language/detect.js +103 -0
- package/dist/language/grammars/LICENSE +24 -0
- package/dist/language/grammars/manifest.json +76 -0
- package/dist/language/grammars/tree-sitter-c.wasm +0 -0
- package/dist/language/grammars/tree-sitter-cpp.wasm +0 -0
- package/dist/language/grammars/tree-sitter-css.wasm +0 -0
- package/dist/language/grammars/tree-sitter-html.wasm +0 -0
- package/dist/language/grammars/tree-sitter-javascript.wasm +0 -0
- package/dist/language/grammars/tree-sitter-php.wasm +0 -0
- package/dist/language/grammars/tree-sitter-python.wasm +0 -0
- package/dist/language/grammars/tree-sitter-ruby.wasm +0 -0
- package/dist/language/grammars/tree-sitter-rust.wasm +0 -0
- package/dist/language/grammars/tree-sitter-swift.wasm +0 -0
- package/dist/language/grammars/tree-sitter-tsx.wasm +0 -0
- package/dist/language/grammars/tree-sitter-typescript.wasm +0 -0
- package/dist/language/install.d.ts +50 -0
- package/dist/language/install.js +293 -0
- package/dist/language/lsp/client.d.ts +97 -0
- package/dist/language/lsp/client.js +337 -0
- package/dist/language/lsp/pool.d.ts +67 -0
- package/dist/language/lsp/pool.js +122 -0
- package/dist/language/lsp/service.d.ts +46 -0
- package/dist/language/lsp/service.js +138 -0
- package/dist/language/native.d.ts +8 -0
- package/dist/language/native.js +100 -0
- package/dist/language/platform.d.ts +14 -0
- package/dist/language/platform.js +20 -0
- package/dist/language/positions.d.ts +20 -0
- package/dist/language/positions.js +46 -0
- package/dist/language/syntax/assets.d.ts +9 -0
- package/dist/language/syntax/assets.js +73 -0
- package/dist/language/syntax/parser.d.ts +24 -0
- package/dist/language/syntax/parser.js +144 -0
- package/dist/language/typescript-capability.d.ts +6 -0
- package/dist/language/typescript-capability.js +42 -0
- package/dist/lisp/config.d.ts +16 -0
- package/dist/lisp/config.js +159 -0
- package/dist/lisp/routing.d.ts +5 -0
- package/dist/lisp/routing.js +24 -0
- package/dist/lisp/runtime.d.ts +21 -0
- package/dist/lisp/runtime.js +83 -0
- package/dist/memory/kiokuko.d.ts +32 -0
- package/dist/memory/kiokuko.js +102 -0
- package/dist/memory/mcp.d.ts +38 -0
- package/dist/memory/mcp.js +211 -0
- package/dist/model/ai-sdk.d.ts +27 -0
- package/dist/model/ai-sdk.js +180 -0
- package/dist/model/chatgpt/login.d.ts +42 -0
- package/dist/model/chatgpt/login.js +180 -0
- package/dist/model/chatgpt/responses.d.ts +41 -0
- package/dist/model/chatgpt/responses.js +202 -0
- package/dist/model/chatgpt/tokens.d.ts +11 -0
- package/dist/model/chatgpt/tokens.js +50 -0
- package/dist/model/connection.d.ts +6 -0
- package/dist/model/connection.js +65 -0
- package/dist/model/context.d.ts +9 -0
- package/dist/model/context.js +69 -0
- package/dist/model/factory.d.ts +25 -0
- package/dist/model/factory.js +88 -0
- package/dist/model/fixed.d.ts +17 -0
- package/dist/model/fixed.js +41 -0
- package/dist/model/reasoning.d.ts +16 -0
- package/dist/model/reasoning.js +62 -0
- package/dist/plugins/api.d.ts +60 -0
- package/dist/plugins/api.js +1 -0
- package/dist/plugins/manager.d.ts +34 -0
- package/dist/plugins/manager.js +261 -0
- package/dist/plugins/package.d.ts +13 -0
- package/dist/plugins/package.js +99 -0
- package/dist/plugins/registry.d.ts +8 -0
- package/dist/plugins/registry.js +14 -0
- package/dist/session/store.d.ts +82 -0
- package/dist/session/store.js +285 -0
- package/dist/session/workspace.d.ts +19 -0
- package/dist/session/workspace.js +73 -0
- package/dist/subagents/processes.d.ts +18 -0
- package/dist/subagents/processes.js +73 -0
- package/dist/subagents/request.d.ts +4 -0
- package/dist/subagents/request.js +21 -0
- package/dist/subagents/service.d.ts +39 -0
- package/dist/subagents/service.js +352 -0
- package/dist/subagents/settings.d.ts +10 -0
- package/dist/subagents/settings.js +32 -0
- package/dist/subagents/types.d.ts +43 -0
- package/dist/subagents/types.js +1 -0
- package/dist/subagents/verification.d.ts +31 -0
- package/dist/subagents/verification.js +178 -0
- package/dist/tools/diff.d.ts +6 -0
- package/dist/tools/diff.js +82 -0
- package/dist/tools/edit.d.ts +3 -0
- package/dist/tools/edit.js +152 -0
- package/dist/tools/files.d.ts +6 -0
- package/dist/tools/files.js +96 -0
- package/dist/tools/formal.d.ts +8 -0
- package/dist/tools/formal.js +77 -0
- package/dist/tools/guard.d.ts +7 -0
- package/dist/tools/guard.js +48 -0
- package/dist/tools/job-tools.d.ts +19 -0
- package/dist/tools/job-tools.js +148 -0
- package/dist/tools/jobs.d.ts +77 -0
- package/dist/tools/jobs.js +181 -0
- package/dist/tools/language.d.ts +6 -0
- package/dist/tools/language.js +174 -0
- package/dist/tools/registry.d.ts +28 -0
- package/dist/tools/registry.js +105 -0
- package/dist/tools/run.d.ts +13 -0
- package/dist/tools/run.js +159 -0
- package/dist/tools/search.d.ts +2 -0
- package/dist/tools/search.js +156 -0
- package/dist/tools/shell-process.d.ts +115 -0
- package/dist/tools/shell-process.js +286 -0
- package/dist/tools/skills.d.ts +2 -0
- package/dist/tools/skills.js +46 -0
- package/dist/tools/web.d.ts +24 -0
- package/dist/tools/web.js +386 -0
- package/docs/ci-repair-20261116.md +30 -0
- package/docs/commonlisp-provider-migration.md +22 -0
- package/docs/commonlisp-qlot-recovery.md +28 -0
- package/docs/commonlisp-tls-recovery.md +28 -0
- package/docs/context-efficiency.md +100 -0
- package/docs/input.md +66 -0
- package/docs/languages.md +117 -0
- package/docs/models.md +85 -0
- package/docs/modkh-evidence.json +641 -0
- package/docs/modkh-failure-comparison.json +675 -0
- package/docs/modkh-namespace.md +39 -0
- package/docs/modkh-qlot-evidence.json +37 -0
- package/docs/modkh-verification.md +173 -0
- package/docs/modkh.md +124 -0
- package/docs/presets.md +19 -0
- package/docs/setup.md +112 -0
- package/docs/subagents.md +134 -0
- package/docs/web.md +57 -0
- package/experiments/presets/common-lisp.lisp +38 -0
- package/experiments/presets/css.lisp +38 -0
- package/experiments/presets/formal.lisp +7 -0
- package/experiments/presets/html.lisp +38 -0
- package/experiments/presets/js.lisp +38 -0
- package/experiments/presets/php.lisp +38 -0
- package/experiments/presets/svelte.lisp +38 -0
- package/experiments/presets/tailwindcss.lisp +24 -0
- package/experiments/presets/ts.lisp +38 -0
- package/package.json +49 -4
- package/plugins/modkh-explorer/index.mjs +3 -0
- package/plugins/modkh-explorer/plugin.json +1 -0
- package/plugins/modkh-worker/index.mjs +3 -0
- package/plugins/modkh-worker/plugin.json +1 -0
- package/skills/kiokuko-dsh/LICENSE +21 -0
- package/skills/kiokuko-dsh/coding-ideal-routine-skill/SKILL.md +106 -0
- package/skills/kiokuko-dsh/japanese-translation-for-oss-models/SKILL.md +65 -0
- package/skills/kiokuko-dsh/kiokuko-architecture/SKILL.md +20 -0
- package/skills/kiokuko-dsh/kiokuko-architecture/references/cases.md +11 -0
- package/skills/kiokuko-dsh/kiokuko-benchmark/SKILL.md +20 -0
- package/skills/kiokuko-dsh/kiokuko-benchmark/references/cases.md +11 -0
- package/skills/kiokuko-dsh/kiokuko-investigate/SKILL.md +20 -0
- package/skills/kiokuko-dsh/kiokuko-investigate/references/cases.md +11 -0
- package/skills/kiokuko-dsh/kiokuko-lisp/SKILL.md +390 -0
- package/skills/kiokuko-dsh/kiokuko-review/SKILL.md +20 -0
- package/skills/kiokuko-dsh/kiokuko-review/references/cases.md +11 -0
- package/skills/kiokuko-dsh/kiokuko-simple-work/SKILL.md +70 -0
- package/skills/kiokuko-dsh/kiokuko-single-purpose-functions/SKILL.md +79 -0
- package/skills/kiokuko-dsh/kiokuko-single-purpose-functions/references/boundaries-and-ownership.md +52 -0
- package/skills/kiokuko-dsh/kiokuko-single-purpose-functions/references/domain-and-types.md +48 -0
- package/skills/kiokuko-dsh/kiokuko-single-purpose-functions/references/effects-and-data.md +43 -0
- package/skills/kiokuko-dsh/kiokuko-single-purpose-functions/references/kiokuko-patterns.md +314 -0
- package/skills/kiokuko-dsh/kiokuko-single-purpose-functions/references/problem-shaping-and-language.md +90 -0
- package/skills/kiokuko-dsh/kiokuko-single-purpose-functions/references/protocols-and-idempotency.md +42 -0
- package/skills/kiokuko-dsh/kiokuko-single-purpose-functions/references/review-checklist.md +92 -0
- package/skills/kiokuko-dsh/kiokuko-single-purpose-functions/references/verification.md +45 -0
- package/skills/kiokuko-dsh/kiokuko-skill-authoring/SKILL.md +20 -0
- package/skills/kiokuko-dsh/kiokuko-skill-authoring/references/cases.md +11 -0
- package/skills/kiokuko-dsh/kiokuko-soul/SKILL.md +25 -0
- package/skills/kiokuko-dsh/kiokuko-technical-writing/SKILL.md +20 -0
- package/skills/kiokuko-dsh/kiokuko-technical-writing/references/cases.md +11 -0
- package/skills/kiokuko-dsh/kiokuko-ui-design-soul/SKILL.md +64 -0
- package/skills/kiokuko-dsh/kiokuko-ui-design-soul/references/accessibility-and-navigation.md +31 -0
- package/skills/kiokuko-dsh/kiokuko-ui-design-soul/references/async-recovery.md +49 -0
- package/skills/kiokuko-dsh/kiokuko-ui-design-soul/references/forms-and-controls.md +35 -0
- package/skills/kiokuko-dsh/kiokuko-ui-design-soul/references/interaction-feedback.md +34 -0
- package/skills/kiokuko-dsh/kiokuko-ui-design-soul/references/responsive-and-platform.md +38 -0
- package/skills/kiokuko-dsh/kiokuko-ui-design-soul/references/safety-and-review.md +43 -0
- package/skills/kiokuko-dsh/kiokuko-ui-design-soul/references/ui-checklist.md +75 -0
- package/skills/kiokuko-dsh/kiokuko-verification/SKILL.md +20 -0
- package/skills/kiokuko-dsh/kiokuko-verification/references/cases.md +11 -0
- package/skills/kiokuko-dsh/manifest.json +168 -0
- package/skills/kiokuko-dsh/memory-reasoning/SKILL.md +44 -0
- package/skills/kiokuko-dsh/one-shot-software-completion/SKILL.md +113 -0
- package/skills/kiokuko-dsh/one-shot-software-completion/references/boundaries-and-lifecycle.md +70 -0
- package/skills/kiokuko-dsh/one-shot-software-completion/references/discovery-and-scope.md +71 -0
- package/skills/kiokuko-dsh/one-shot-software-completion/references/failure-recovery.md +43 -0
- package/skills/kiokuko-dsh/one-shot-software-completion/references/verification-and-completion.md +73 -0
- package/skills/kiokuko-dsh/veteran-programmer-skill/SKILL.md +66 -0
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
|
|
2
|
+
|
|
3
|
+
# `code.domain.v1` — domain rules and narrow types
|
|
4
|
+
|
|
5
|
+
Select this expert when the function decides business rules, computes values, classifies states, or moves an entity through a state machine.
|
|
6
|
+
|
|
7
|
+
## Contract
|
|
8
|
+
|
|
9
|
+
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.
|
|
10
|
+
|
|
11
|
+
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.
|
|
12
|
+
|
|
13
|
+
Define:
|
|
14
|
+
|
|
15
|
+
- the valid input state;
|
|
16
|
+
- the exact transition or result;
|
|
17
|
+
- invariants preserved before and after;
|
|
18
|
+
- expected domain rejections;
|
|
19
|
+
- whether the operation is total or intentionally partial.
|
|
20
|
+
|
|
21
|
+
## Cohesion rules
|
|
22
|
+
|
|
23
|
+
- A function may contain several steps when they implement one rule and change for the same reason.
|
|
24
|
+
- Split unrelated policy decisions even if they currently share a caller.
|
|
25
|
+
- Do not extract trivial wrappers that merely rename an expression without creating a useful contract.
|
|
26
|
+
- Do not mix “decide what should happen” with “persist or publish it” when the decision can be represented as data.
|
|
27
|
+
|
|
28
|
+
Example:
|
|
29
|
+
|
|
30
|
+
```ts
|
|
31
|
+
type Transition =
|
|
32
|
+
| { kind: 'advance'; next: State }
|
|
33
|
+
| { kind: 'reject'; code: 'stale_revision' | 'terminal' };
|
|
34
|
+
|
|
35
|
+
function decideAdvance(current: State, expectedRevision: number): Transition {
|
|
36
|
+
if (current.revision !== expectedRevision) return { kind: 'reject', code: 'stale_revision' };
|
|
37
|
+
if (current.status === 'completed') return { kind: 'reject', code: 'terminal' };
|
|
38
|
+
return { kind: 'advance', next: { ...current, revision: current.revision + 1 } };
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Failure behavior
|
|
43
|
+
|
|
44
|
+
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.
|
|
45
|
+
|
|
46
|
+
## Focused verification
|
|
47
|
+
|
|
48
|
+
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.
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
|
|
2
|
+
|
|
3
|
+
# `code.effects.v1` — effects, data, and resource lifetime
|
|
4
|
+
|
|
5
|
+
Select this expert when a contract touches a database, filesystem, network, subprocess, cache, message bus, clock, random source, UI runtime, or long-lived resource.
|
|
6
|
+
|
|
7
|
+
## Contract
|
|
8
|
+
|
|
9
|
+
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.
|
|
10
|
+
|
|
11
|
+
Separate four concerns when practical:
|
|
12
|
+
|
|
13
|
+
1. validate and authorize the request;
|
|
14
|
+
2. decide the domain change;
|
|
15
|
+
3. apply effects under an explicit atomicity policy;
|
|
16
|
+
4. translate infrastructure outcomes into the public result.
|
|
17
|
+
|
|
18
|
+
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.
|
|
19
|
+
|
|
20
|
+
## Data integrity
|
|
21
|
+
|
|
22
|
+
- State which writes are atomic and which partial outcomes are possible.
|
|
23
|
+
- Use compare-and-set, revision checks, unique constraints, or locks where concurrent writers can violate invariants.
|
|
24
|
+
- Check affected-row counts when they prove the intended state transition occurred.
|
|
25
|
+
- Never claim persistence before durable completion.
|
|
26
|
+
- Keep schema or serialization compatibility explicit at stored-data boundaries.
|
|
27
|
+
- Do not swallow a failed cleanup, rollback, or close when it changes correctness.
|
|
28
|
+
|
|
29
|
+
## External effects
|
|
30
|
+
|
|
31
|
+
- Bound time, output, memory, and retries.
|
|
32
|
+
- Define cancellation semantics: cancelling the UI is not the same as cancelling the work.
|
|
33
|
+
- Close files, streams, transactions, child processes, and subscriptions on success and failure.
|
|
34
|
+
- Avoid fire-and-forget work unless ownership, failure reporting, and process lifetime are deliberately defined.
|
|
35
|
+
- Sanitize logs and previews; do not leak secrets or private payloads through diagnostic output.
|
|
36
|
+
|
|
37
|
+
## Testing seam
|
|
38
|
+
|
|
39
|
+
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.
|
|
40
|
+
|
|
41
|
+
## Focused verification
|
|
42
|
+
|
|
43
|
+
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.
|
|
@@ -0,0 +1,314 @@
|
|
|
1
|
+
<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
|
|
2
|
+
|
|
3
|
+
# Single-purpose implementation patterns
|
|
4
|
+
|
|
5
|
+
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, and reuse existing project helpers before creating substitutes.
|
|
6
|
+
|
|
7
|
+
## 1. Hostile boundary, constrained private core
|
|
8
|
+
|
|
9
|
+
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.
|
|
10
|
+
|
|
11
|
+
This Node example accepts arbitrary in-process objects. Reject Proxy objects before reflection and accessors without invoking them. Accept only plain records with enumerable own data properties; return an independent value. For already decoded data-only input, reuse its established normalization boundary instead.
|
|
12
|
+
|
|
13
|
+
<!-- example:parseWindow -->
|
|
14
|
+
```ts
|
|
15
|
+
import { isProxy } from 'node:util/types';
|
|
16
|
+
|
|
17
|
+
interface ValidatedWindow {
|
|
18
|
+
readonly start: number;
|
|
19
|
+
readonly limit: number;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export function parseWindow(value: unknown): ValidatedWindow {
|
|
23
|
+
if (typeof value !== 'object' || value === null || isProxy(value)) {
|
|
24
|
+
throw new Error('window must be a plain data object');
|
|
25
|
+
}
|
|
26
|
+
const prototype = Object.getPrototypeOf(value);
|
|
27
|
+
if (prototype !== Object.prototype && prototype !== null) throw new Error('invalid window prototype');
|
|
28
|
+
const keys = Reflect.ownKeys(value);
|
|
29
|
+
if (keys.length !== 2 || !keys.includes('start') || !keys.includes('limit')) throw new Error('invalid window fields');
|
|
30
|
+
const descriptors = Object.getOwnPropertyDescriptors(value);
|
|
31
|
+
const startField = descriptors.start!;
|
|
32
|
+
const limitField = descriptors.limit!;
|
|
33
|
+
if (!('value' in startField) || !startField.enumerable
|
|
34
|
+
|| !('value' in limitField) || !limitField.enumerable) throw new Error('window requires data properties');
|
|
35
|
+
const start: unknown = startField.value;
|
|
36
|
+
const limit: unknown = limitField.value;
|
|
37
|
+
if (typeof start !== 'number' || !Number.isInteger(start) || start < 0) throw new Error('window start is invalid');
|
|
38
|
+
if (typeof limit !== 'number' || !Number.isInteger(limit) || limit < 1 || limit > 100) throw new Error('window limit is invalid');
|
|
39
|
+
return { start, limit };
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
function calculateEnd(window: ValidatedWindow): number {
|
|
43
|
+
return window.start + window.limit;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
export function endOfWindow(value: unknown): number {
|
|
47
|
+
return calculateEnd(parseWindow(value));
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
<!-- /example:parseWindow -->
|
|
51
|
+
|
|
52
|
+
Use the project's error type and validation library where available. Do not make `calculateEnd` accept `unknown` or repeat transport validation throughout the domain.
|
|
53
|
+
|
|
54
|
+
## 2. Closed schema at a request boundary
|
|
55
|
+
|
|
56
|
+
Use a schema library the project already depends on; do not add one for a boundary the standard library can guard. The schema is the boundary: reject unknown fields when the protocol is closed, bound every collection and string, and require an explicit default for optional inputs. Internal helpers consume the validated output or a narrower domain value, never the raw transport shape.
|
|
57
|
+
|
|
58
|
+
The accepted representation is a plain data record containing strings, a dense ordinary string array, and an optional integer. Normalize this fixed shape without invoking getters or Proxy traps, then validate the owned data with the existing schema library. This example defaults `limit` only when its key is omitted; explicit `undefined` and `null` are invalid. Paths are non-empty strings of at most 4096 characters, with at most 100 paths. No filesystem access or path authorization is implied.
|
|
59
|
+
|
|
60
|
+
<!-- example:parseRequest -->
|
|
61
|
+
```ts
|
|
62
|
+
import { isProxy } from 'node:util/types';
|
|
63
|
+
import { z } from 'zod';
|
|
64
|
+
|
|
65
|
+
const requestSchema = z.object({
|
|
66
|
+
requestId: z.string().min(1).max(256),
|
|
67
|
+
paths: z.array(z.string().min(1).max(4096)).max(100),
|
|
68
|
+
limit: z.number().int().min(1).max(100),
|
|
69
|
+
}).strict();
|
|
70
|
+
type Request = z.infer<typeof requestSchema>;
|
|
71
|
+
|
|
72
|
+
export function parseRequest(value: unknown): Request {
|
|
73
|
+
const invalid = () => new Error('invalid request');
|
|
74
|
+
if (typeof value !== 'object' || value === null || isProxy(value)) throw invalid();
|
|
75
|
+
const prototype = Object.getPrototypeOf(value);
|
|
76
|
+
if (prototype !== Object.prototype && prototype !== null) throw invalid();
|
|
77
|
+
const keys = Reflect.ownKeys(value);
|
|
78
|
+
if (keys.length > 3 || keys.some(key => key !== 'requestId' && key !== 'paths' && key !== 'limit')) throw invalid();
|
|
79
|
+
const data: Record<string, unknown> = Object.create(null);
|
|
80
|
+
for (const key of keys) {
|
|
81
|
+
const descriptor = Object.getOwnPropertyDescriptor(value, key)!;
|
|
82
|
+
if (!descriptor.enumerable || !('value' in descriptor)) throw invalid();
|
|
83
|
+
data[key as string] = descriptor.value;
|
|
84
|
+
}
|
|
85
|
+
const paths = data.paths;
|
|
86
|
+
if (typeof paths !== 'object' || paths === null || isProxy(paths)
|
|
87
|
+
|| !Array.isArray(paths) || Object.getPrototypeOf(paths) !== Array.prototype) throw invalid();
|
|
88
|
+
const length: number = Object.getOwnPropertyDescriptor(paths, 'length')!.value;
|
|
89
|
+
if (length > 100 || Reflect.ownKeys(paths).length !== length + 1) throw invalid();
|
|
90
|
+
const ownedPaths: string[] = [];
|
|
91
|
+
for (let index = 0; index < length; index++) {
|
|
92
|
+
const descriptor = Object.getOwnPropertyDescriptor(paths, String(index));
|
|
93
|
+
if (!descriptor || !descriptor.enumerable || !('value' in descriptor)
|
|
94
|
+
|| typeof descriptor.value !== 'string') throw invalid();
|
|
95
|
+
ownedPaths.push(descriptor.value);
|
|
96
|
+
}
|
|
97
|
+
data.paths = ownedPaths;
|
|
98
|
+
if (!Object.hasOwn(data, 'limit')) data.limit = 20;
|
|
99
|
+
const parsed = requestSchema.safeParse(data);
|
|
100
|
+
if (!parsed.success) throw invalid();
|
|
101
|
+
return parsed.data;
|
|
102
|
+
}
|
|
103
|
+
```
|
|
104
|
+
<!-- /example:parseRequest -->
|
|
105
|
+
|
|
106
|
+
## 3. Exact optional values
|
|
107
|
+
|
|
108
|
+
Omit absent optional properties rather than assigning ambiguous placeholders.
|
|
109
|
+
|
|
110
|
+
```ts
|
|
111
|
+
interface Candidate {
|
|
112
|
+
readonly id: string;
|
|
113
|
+
readonly description?: string;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
function candidate(id: string, description: string | undefined): Candidate {
|
|
117
|
+
return {
|
|
118
|
+
id,
|
|
119
|
+
...(description === undefined ? {} : { description }),
|
|
120
|
+
};
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Use the equivalent convention in languages that distinguish missing, null, and empty values.
|
|
125
|
+
|
|
126
|
+
## 4. Immutable transformation
|
|
127
|
+
|
|
128
|
+
Return a new value and leave the caller's input untouched, unless mutation is the explicit API contract. When the transformation is the change being made, prove it with a check that compares the input before and after and asserts the result is a different object.
|
|
129
|
+
|
|
130
|
+
## 5. Explicit variable dependencies
|
|
131
|
+
|
|
132
|
+
Keep time and randomness out of pure ranking, hashing, transition, and validation functions.
|
|
133
|
+
|
|
134
|
+
```ts
|
|
135
|
+
interface Dependencies {
|
|
136
|
+
readonly now: () => string;
|
|
137
|
+
readonly createId: () => string;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
interface CreatedRecord {
|
|
141
|
+
readonly id: string;
|
|
142
|
+
readonly createdAt: string;
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
function createRecord(dependencies: Dependencies): CreatedRecord {
|
|
146
|
+
return {
|
|
147
|
+
id: dependencies.createId(),
|
|
148
|
+
createdAt: dependencies.now(),
|
|
149
|
+
};
|
|
150
|
+
}
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Production composition supplies real dependencies; tests supply deterministic ones.
|
|
154
|
+
|
|
155
|
+
## 6. Transaction-agnostic store, transaction-owning use case
|
|
156
|
+
|
|
157
|
+
The store performs persistence. The service or use case owns the atomic operation.
|
|
158
|
+
|
|
159
|
+
```ts
|
|
160
|
+
type Transaction = { execute(sql: string, parameters: readonly unknown[]): void };
|
|
161
|
+
|
|
162
|
+
function insertItem(transaction: Transaction, id: string, value: string): void {
|
|
163
|
+
transaction.execute('INSERT INTO items (id, value) VALUES (?, ?)', [id, value]);
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
function createItem(runTransaction: (operation: (t: Transaction) => void) => void, id: string): void {
|
|
167
|
+
runTransaction((transaction) => {
|
|
168
|
+
insertItem(transaction, id, 'value');
|
|
169
|
+
transaction.execute('INSERT INTO audit_events (event_type, target_id) VALUES (?, ?)', ['item_created', id]);
|
|
170
|
+
});
|
|
171
|
+
}
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
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.
|
|
175
|
+
|
|
176
|
+
## 7. Validate stored data before domain use
|
|
177
|
+
|
|
178
|
+
Driver types and generated models are not always runtime proof, especially across migrations or external storage.
|
|
179
|
+
|
|
180
|
+
```ts
|
|
181
|
+
interface StoredItem {
|
|
182
|
+
readonly id: string;
|
|
183
|
+
readonly revision: number;
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
function parseStoredItem(row: Record<string, unknown> | undefined): StoredItem {
|
|
187
|
+
if (row === undefined) throw new Error('Item not found');
|
|
188
|
+
if (typeof row.id !== 'string'
|
|
189
|
+
|| typeof row.revision !== 'number'
|
|
190
|
+
|| !Number.isInteger(row.revision)
|
|
191
|
+
|| row.revision < 1) {
|
|
192
|
+
throw new Error('Stored item is invalid');
|
|
193
|
+
}
|
|
194
|
+
return { id: row.id, revision: row.revision };
|
|
195
|
+
}
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
Do not include malformed row contents in a public error.
|
|
199
|
+
|
|
200
|
+
## 8. Safe public error mapping
|
|
201
|
+
|
|
202
|
+
Public messages should be stable. Keep only allowlisted bounded details.
|
|
203
|
+
|
|
204
|
+
```ts
|
|
205
|
+
interface PublicFailure {
|
|
206
|
+
readonly code: 'busy' | 'invalid' | 'internal';
|
|
207
|
+
readonly message: string;
|
|
208
|
+
readonly retryAfterSeconds?: number;
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
function publicFailure(error: unknown): PublicFailure {
|
|
212
|
+
if (isBusyFailure(error)) {
|
|
213
|
+
return {
|
|
214
|
+
code: 'busy',
|
|
215
|
+
message: 'Service is busy',
|
|
216
|
+
retryAfterSeconds: clampRetryDelay(error.retryAfterSeconds),
|
|
217
|
+
};
|
|
218
|
+
}
|
|
219
|
+
if (isValidationFailure(error)) {
|
|
220
|
+
return { code: 'invalid', message: 'Request is invalid' };
|
|
221
|
+
}
|
|
222
|
+
return { code: 'internal', message: 'Internal error' };
|
|
223
|
+
}
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
Do not copy unknown exception messages, submitted values, credentials, URLs with secret query parameters, or provider bodies into public output.
|
|
227
|
+
|
|
228
|
+
## 9. Preserve operation and cleanup failures
|
|
229
|
+
|
|
230
|
+
When both fail, retain both failures without replacing the primary one.
|
|
231
|
+
|
|
232
|
+
<!-- example:useResource -->
|
|
233
|
+
```ts
|
|
234
|
+
interface Resource { close(): Promise<void>; }
|
|
235
|
+
|
|
236
|
+
export async function useResource<T>(open: () => Promise<Resource>, operation: (r: Resource) => Promise<T>): Promise<T> {
|
|
237
|
+
const resource = await open();
|
|
238
|
+
let result: T;
|
|
239
|
+
try {
|
|
240
|
+
result = await operation(resource);
|
|
241
|
+
} catch (operationFailure) {
|
|
242
|
+
try {
|
|
243
|
+
await resource.close();
|
|
244
|
+
} catch (cleanupFailure) {
|
|
245
|
+
throw new AggregateError([operationFailure, cleanupFailure], 'operation and cleanup failed');
|
|
246
|
+
}
|
|
247
|
+
throw operationFailure;
|
|
248
|
+
}
|
|
249
|
+
// Outside the operation catch: a failed close must never cause a second close.
|
|
250
|
+
await resource.close();
|
|
251
|
+
return result;
|
|
252
|
+
}
|
|
253
|
+
```
|
|
254
|
+
<!-- /example:useResource -->
|
|
255
|
+
|
|
256
|
+
Close exactly once after every successful open, including successful operations. Preserve thrown values even when they are `undefined`. Use the language's structured multi-error or error-chaining mechanism; Lisp's `unwind-protect` alone does not preserve both conditions. Forced worker termination and recovery belong to the host contract.
|
|
257
|
+
|
|
258
|
+
## 10. Classify failures by structured fields
|
|
259
|
+
|
|
260
|
+
Prefer error types, codes, status values, or discriminated variants over message matching. A guard should check the structured field and its value, never a substring of the message: an unrelated exception containing "busy" or "timeout" is not retryable.
|
|
261
|
+
|
|
262
|
+
```ts
|
|
263
|
+
function isRetryableFailure(error: unknown): error is RetryableFailure {
|
|
264
|
+
return error instanceof Error
|
|
265
|
+
&& 'code' in error && error.code === 'temporarily_unavailable'
|
|
266
|
+
&& 'retryAfterSeconds' in error && typeof error.retryAfterSeconds === 'number';
|
|
267
|
+
}
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
## 11. Immutable replay identity
|
|
271
|
+
|
|
272
|
+
Bind every field that changes the meaning of an idempotent operation.
|
|
273
|
+
|
|
274
|
+
```ts
|
|
275
|
+
interface BoundRequest {
|
|
276
|
+
readonly operation: string;
|
|
277
|
+
readonly subjectId: string;
|
|
278
|
+
readonly expectedRevision: number;
|
|
279
|
+
readonly mode: 'validate' | 'apply';
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
function replayMatches(left: BoundRequest, right: BoundRequest): boolean {
|
|
283
|
+
return left.operation === right.operation
|
|
284
|
+
&& left.subjectId === right.subjectId
|
|
285
|
+
&& left.expectedRevision === right.expectedRevision
|
|
286
|
+
&& left.mode === right.mode;
|
|
287
|
+
}
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
Reusing an identity with changed bound input is a conflict, not a second mutation.
|
|
291
|
+
|
|
292
|
+
## 12. Compare-and-swap filesystem changes
|
|
293
|
+
|
|
294
|
+
When concurrent changes or independently owned files must be protected, a plain write, rename, or delete is insufficient. Use the project's atomic compare-and-swap helper, and make the contract explicit about expected content, expected file and parent-directory identity, alternate paths that must remain absent, restrictive mode, reverse-order rollback, and an explicit ambiguous-cleanup failure.
|
|
295
|
+
|
|
296
|
+
## 13. Secret non-echo
|
|
297
|
+
|
|
298
|
+
Assert that rejected input is not echoed: submit a sentinel value, trigger the validation failure, and assert the error message does not contain the sentinel.
|
|
299
|
+
|
|
300
|
+
## 14. Deterministic output
|
|
301
|
+
|
|
302
|
+
For canonical order, hashes, manifests, and rankings, construct semantically equivalent inputs with different insertion order and assert identical output.
|
|
303
|
+
|
|
304
|
+
## 15. Verification sequence
|
|
305
|
+
|
|
306
|
+
Run commands that actually exist in the repository:
|
|
307
|
+
|
|
308
|
+
1. the narrowest test covering the changed contract;
|
|
309
|
+
2. relevant integration tests;
|
|
310
|
+
3. type or static checks;
|
|
311
|
+
4. the broader test suite when shared behavior changed;
|
|
312
|
+
5. build and package checks when distribution changed.
|
|
313
|
+
|
|
314
|
+
Report skipped commands and failures exactly. Do not invent a lint, formatter, build, or test command that the project does not define.
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
|
|
2
|
+
|
|
3
|
+
# `code.modeling.v1` — problem shaping and representation design
|
|
4
|
+
|
|
5
|
+
Select this expert when a contract defines a public data shape, introduces
|
|
6
|
+
domain vocabulary, or translates between human intent, domain values, storage,
|
|
7
|
+
transport, serialization, and consumer or UI representations.
|
|
8
|
+
|
|
9
|
+
Do not select it for a representation-preserving mechanical change merely
|
|
10
|
+
because the work modifies code. This expert does not require Lisp syntax, a
|
|
11
|
+
Lisp runtime, macros, a DSL, or a separate design document.
|
|
12
|
+
|
|
13
|
+
## Contract
|
|
14
|
+
|
|
15
|
+
Turn the human problem into named concepts and explicit transformations before
|
|
16
|
+
letting a database schema, ORM model, framework object, wire format, or UI state
|
|
17
|
+
become the accidental product contract.
|
|
18
|
+
|
|
19
|
+
For a non-trivial selected contract, make these items explicit in the working
|
|
20
|
+
plan or review notes, without creating a new artifact unless the user asks:
|
|
21
|
+
|
|
22
|
+
1. **Intent:** identify the actor, their goal, the observable result, and data
|
|
23
|
+
that must remain hidden or out of scope.
|
|
24
|
+
2. **Representation map:** list only the layers that actually exist, using this
|
|
25
|
+
shape as a guide: `human intent -> domain concept -> storage/input shape ->
|
|
26
|
+
public shape -> consumer shape`.
|
|
27
|
+
3. **Consumer-first shape:** define what the external caller or next layer
|
|
28
|
+
needs before choosing how to retrieve, serialize, or display it.
|
|
29
|
+
4. **Named transformations:** use names that reveal the concept and direction,
|
|
30
|
+
such as `rowToArticle`, `articleToApiResponse`, or
|
|
31
|
+
`apiResponseToArticleViewState`.
|
|
32
|
+
5. **Loss and failure policy:** state what is omitted, normalized, derived,
|
|
33
|
+
rejected, or intentionally impossible to reconstruct at each boundary.
|
|
34
|
+
6. **Abstraction threshold:** start with direct values and cohesive functions.
|
|
35
|
+
Extract shared vocabulary after meaningful repetition appears; introduce a
|
|
36
|
+
DSL, macro, code generator, or generic framework only when the stable pattern
|
|
37
|
+
and its benefit are evidenced.
|
|
38
|
+
|
|
39
|
+
## Representation boundaries
|
|
40
|
+
|
|
41
|
+
- Storage shapes serve persistence and query needs; they are not automatically
|
|
42
|
+
domain or public shapes.
|
|
43
|
+
- Domain shapes name legal concepts and invariants without inheriting transport
|
|
44
|
+
or framework accidents.
|
|
45
|
+
- Public API and event shapes are compatibility and disclosure contracts. Build
|
|
46
|
+
them from allowlisted fields rather than serializing internal objects.
|
|
47
|
+
- Consumer and UI shapes serve rendering and interaction state. Do not force
|
|
48
|
+
components to understand database relations or transport-only nullability.
|
|
49
|
+
- Use distinct shapes for distinct audiences when list, detail, administrative,
|
|
50
|
+
and public views carry different concepts or disclosure rules.
|
|
51
|
+
|
|
52
|
+
Pair this expert with `code.boundary.v1` when the transformation crosses an
|
|
53
|
+
untrusted or public boundary. Pair it with `code.domain.v1` when the named shape
|
|
54
|
+
owns business states, invariants, or transitions. Stay within the three-expert
|
|
55
|
+
limit and select only risks owned by the same cohesive contract.
|
|
56
|
+
|
|
57
|
+
## Failure modes
|
|
58
|
+
|
|
59
|
+
For a non-trivial design, consider one nearby extension or recovery without
|
|
60
|
+
implementing it. For example, after adding a pricing variant, identify where a
|
|
61
|
+
second variant would reuse validation and preserve existing callers. This checks
|
|
62
|
+
the ownership boundary; it does not justify a speculative plugin framework.
|
|
63
|
+
Review concrete names, dependency direction and duplicated rules, not line counts.
|
|
64
|
+
|
|
65
|
+
- Returning an ORM entity, database row, or framework object directly as a
|
|
66
|
+
public response.
|
|
67
|
+
- Treating storage column names or relations as a stable external API by
|
|
68
|
+
accident.
|
|
69
|
+
- Reusing one DTO for audiences whose visibility or interaction needs differ.
|
|
70
|
+
- Mixing server response state, domain state, and UI state in one mutable type.
|
|
71
|
+
- Adding wrappers that rename syntax but create no semantic contract.
|
|
72
|
+
- Generalizing one instance into a DSL or metaprogramming layer before stable
|
|
73
|
+
repetition exists.
|
|
74
|
+
|
|
75
|
+
## Focused verification
|
|
76
|
+
|
|
77
|
+
Test the observable shape and transformation rather than the current storage or
|
|
78
|
+
framework implementation:
|
|
79
|
+
|
|
80
|
+
- assert the exact allowed public fields and the absence of internal or secret
|
|
81
|
+
fields;
|
|
82
|
+
- cover missing, optional, normalized, derived, and rejected values;
|
|
83
|
+
- verify intentional information loss or round-trip behavior where relevant;
|
|
84
|
+
- prove that a storage-layout or transport-fixture change does not silently
|
|
85
|
+
redefine the public concept;
|
|
86
|
+
- test audience-specific shapes independently when their contracts differ.
|
|
87
|
+
|
|
88
|
+
This guidance adapts the problem-shaping philosophy described in
|
|
89
|
+
<https://zenn.dev/circleback/articles/what-is-lisp>; it applies that philosophy
|
|
90
|
+
across programming languages and does not reproduce the article text.
|
package/skills/kiokuko-dsh/kiokuko-single-purpose-functions/references/protocols-and-idempotency.md
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
|
|
2
|
+
|
|
3
|
+
# `code.protocol.v1` — protocols, concurrency, and idempotency
|
|
4
|
+
|
|
5
|
+
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.
|
|
6
|
+
|
|
7
|
+
## Contract
|
|
8
|
+
|
|
9
|
+
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.
|
|
10
|
+
|
|
11
|
+
Define:
|
|
12
|
+
|
|
13
|
+
- the stable operation or request identity;
|
|
14
|
+
- which input fields are bound to that identity;
|
|
15
|
+
- the exact legal source states;
|
|
16
|
+
- the expected revision or version;
|
|
17
|
+
- retry and replay behavior;
|
|
18
|
+
- what a duplicate with identical input returns;
|
|
19
|
+
- what a duplicate identity with changed input returns;
|
|
20
|
+
- which actor owns each transition.
|
|
21
|
+
|
|
22
|
+
## Idempotency
|
|
23
|
+
|
|
24
|
+
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.
|
|
25
|
+
|
|
26
|
+
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.
|
|
27
|
+
|
|
28
|
+
## Concurrency
|
|
29
|
+
|
|
30
|
+
- Check revision and allowed source state in the same atomic mutation.
|
|
31
|
+
- Make ambiguous candidates fail closed or remain unbound; never guess.
|
|
32
|
+
- Treat zero or multiple affected rows as evidence that the expected transition did not occur.
|
|
33
|
+
- Prevent stale completion, retry, or callback results from overwriting newer state.
|
|
34
|
+
- Keep terminal states terminal unless the protocol explicitly defines a new revision or recovery transition.
|
|
35
|
+
|
|
36
|
+
## Compatibility
|
|
37
|
+
|
|
38
|
+
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.
|
|
39
|
+
|
|
40
|
+
## Focused verification
|
|
41
|
+
|
|
42
|
+
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.
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
|
|
2
|
+
|
|
3
|
+
# Function-contract coding and review checklist
|
|
4
|
+
|
|
5
|
+
Use this checklist while implementing, debugging, refactoring, or reviewing code in any language or repository. Apply only the sections relevant to the change.
|
|
6
|
+
|
|
7
|
+
Read this file for a comprehensive code review or final verification, especially when the change crosses several code contracts. For an ordinary edit inside one cohesive contract, use the focused `verification.md` sequence instead: that file owns the evidence procedure, this one owns the review dimensions to sweep.
|
|
8
|
+
|
|
9
|
+
## Scope
|
|
10
|
+
|
|
11
|
+
- [ ] The change addresses one stated behavior.
|
|
12
|
+
- [ ] No unrelated cleanup, public API redesign, migration rewrite, dependency replacement, or broad type churn was added.
|
|
13
|
+
- [ ] Relevant architecture, security, data, protocol, and feature contracts were checked.
|
|
14
|
+
|
|
15
|
+
## Function responsibility
|
|
16
|
+
|
|
17
|
+
- [ ] Each changed function has one cohesive externally observable responsibility.
|
|
18
|
+
- [ ] Boundary, domain, persistence, adapter, and orchestrator roles are not mixed without a specific reason.
|
|
19
|
+
- [ ] Extraction created a meaningful operation rather than a one-line wrapper.
|
|
20
|
+
- [ ] An atomic state machine, transaction, or cleanup sequence was not fragmented into an unreadable chain.
|
|
21
|
+
|
|
22
|
+
## Inputs and ownership
|
|
23
|
+
|
|
24
|
+
- [ ] Externally influenced values are untrusted until runtime validation.
|
|
25
|
+
- [ ] Strings, collections, nesting, retries, and output are bounded.
|
|
26
|
+
- [ ] Closed shapes reject unknown fields where required.
|
|
27
|
+
- [ ] Hostile input cannot trigger unsafe getters, proxies, hooks, or custom serialization during validation.
|
|
28
|
+
- [ ] Validated values are copied into owned data where references could escape.
|
|
29
|
+
- [ ] Caller-owned input is not mutated.
|
|
30
|
+
- [ ] Missing, null, empty, unknown, unavailable, and invalid states remain distinct where required.
|
|
31
|
+
- [ ] No new unchecked cast, suppressed diagnostic, or type escape hatch bypasses a boundary check.
|
|
32
|
+
|
|
33
|
+
## Domain behavior
|
|
34
|
+
|
|
35
|
+
- [ ] Pure calculations, normalization, ranking, and state transitions have no hidden I/O.
|
|
36
|
+
- [ ] Time, randomness, environment, locale, and external capabilities are explicit dependencies.
|
|
37
|
+
- [ ] Canonical order and serialization are deterministic where identity or hashing depends on them.
|
|
38
|
+
- [ ] Preconditions and postconditions are represented in code or tests.
|
|
39
|
+
|
|
40
|
+
## Errors, privacy, and security
|
|
41
|
+
|
|
42
|
+
- [ ] Expected failures use the project’s narrowest existing error or result category.
|
|
43
|
+
- [ ] Public messages and details are stable, bounded, and allowlisted.
|
|
44
|
+
- [ ] Invalid values, credentials, private data, provider bodies, and secret-like strings are not echoed.
|
|
45
|
+
- [ ] Unknown internal failures are not exposed as raw messages.
|
|
46
|
+
- [ ] Primary and cleanup failures are both preserved when both occur.
|
|
47
|
+
- [ ] No catch block turns corruption, conflict, partial failure, or uncertain state into success.
|
|
48
|
+
- [ ] Authorization, normalization, sanitization, and secret checks remain in the successful execution path.
|
|
49
|
+
|
|
50
|
+
## Persistence, transactions, and resources
|
|
51
|
+
|
|
52
|
+
- [ ] Queries are parameterized where applicable and kept out of transport or presentation code.
|
|
53
|
+
- [ ] Stored data is validated before becoming domain state.
|
|
54
|
+
- [ ] Low-level persistence functions remain transaction-agnostic when they compose inside a use case.
|
|
55
|
+
- [ ] One clear owner controls the transaction or resource lifecycle.
|
|
56
|
+
- [ ] No network, user prompt, child process, or unrelated slow work runs while holding a write transaction or scarce lock.
|
|
57
|
+
- [ ] Retry classification uses structured error information instead of message text.
|
|
58
|
+
- [ ] Ambiguous commit and incomplete cleanup states prevent unsafe compensation.
|
|
59
|
+
|
|
60
|
+
## Idempotency and identity
|
|
61
|
+
|
|
62
|
+
- [ ] Exact replay and changed-input conflict are distinguished.
|
|
63
|
+
- [ ] Every meaning-bearing input participates in replay, generation, revision, or cache identity.
|
|
64
|
+
- [ ] Expected-version checks happen before mutation.
|
|
65
|
+
- [ ] Independently owned or newer state is not silently overwritten.
|
|
66
|
+
- [ ] Partial or ambiguous cleanup is reported rather than presented as success.
|
|
67
|
+
|
|
68
|
+
## External contracts
|
|
69
|
+
|
|
70
|
+
- [ ] Public APIs, command output, exit status, schemas, event order, and serialized formats remain stable unless intentionally changed.
|
|
71
|
+
- [ ] Protocol output is not contaminated by diagnostics or logging.
|
|
72
|
+
- [ ] Authentication, authorization, origin, path, and confirmation boundaries remain intact.
|
|
73
|
+
- [ ] Package manifests include required runtime files.
|
|
74
|
+
- [ ] Migration history and recorded checksums are not rewritten in place.
|
|
75
|
+
- [ ] Managed markers, file modes, line endings, and unrelated user content are preserved where applicable.
|
|
76
|
+
|
|
77
|
+
## Tests
|
|
78
|
+
|
|
79
|
+
- [ ] A regression test captures the original failure or falsifying counterexample.
|
|
80
|
+
- [ ] Normal success behavior is covered.
|
|
81
|
+
- [ ] Empty, minimum, maximum, and exact-boundary values are covered where relevant.
|
|
82
|
+
- [ ] Wrong types, malformed shapes, unknown fields, or hostile values are covered at changed boundaries.
|
|
83
|
+
- [ ] Caller-owned input immutability is asserted where plausible.
|
|
84
|
+
- [ ] Secret and invalid-value non-echo is asserted where applicable.
|
|
85
|
+
- [ ] Each changed expected failure category is asserted.
|
|
86
|
+
- [ ] Retry bounds and non-retryable failures are covered when retry behavior changes.
|
|
87
|
+
- [ ] Rollback, ambiguous commit, and dual operation/cleanup failures are covered when ownership changes.
|
|
88
|
+
- [ ] Exact replay and changed-input conflict are covered when idempotency changes.
|
|
89
|
+
- [ ] Integration tests exercise the real storage, filesystem, network, process, or protocol boundary when adapter behavior changes.
|
|
90
|
+
- [ ] Tests assert observable contracts, not incidental private call order.
|
|
91
|
+
|
|
92
|
+
Report the run commands, results, and residual risk exactly as `verification.md` requires.
|