wydcode 0.4.3

package/LICENSE

@@ -0,0 +1,100 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             MumpixDB
+
+Licensed Work:        wydcode and Socra Harness source code, compiled binaries,
+                      build tooling, and documentation distributed in this
+                      repository.
+
+Additional Use Grant: You may make production use of the Licensed Work, provided
+                      Your use does not include offering the Licensed Work to
+                      third parties as a commercial hosted service.
+
+Change Date:          2030-07-09
+
+Change License:       Apache License, Version 2.0
+
+For alternative licensing arrangements, contact MumpixDB.
+
+Business Source License 1.1
+
+License text copyright (c) 2024 MariaDB plc, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB plc.
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production
+use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under the
+terms of the Change License, and the rights granted in the paragraph above
+terminate.
+
+If your use of the Licensed Work does not comply with the requirements currently
+in effect as described in this License, you must purchase a commercial license
+from the Licensor, its affiliated entities, or authorized resellers, or you must
+refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works of
+the Licensed Work, are subject to this License. This License applies separately
+for each version of the Licensed Work and the Change Date may vary for each
+version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy of
+the Licensed Work. If you receive the Licensed Work in original or modified form
+from a third party, the terms and conditions set forth in this License apply to
+your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other versions
+of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of Licensor
+or its affiliates (provided that you may use a trademark or logo of Licensor as
+expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN
+"AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license your
+works, and to refer to it using the trademark "Business Source License", as long
+as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business Source
+License" name and trademark, Licensor covenants to MariaDB, and to all other
+recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None" to specify a Change
+   Date.
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+For more information on the Business Source License, see
+https://mariadb.com/bsl11/.

package/NOTICE

@@ -0,0 +1,5 @@
+wydcode and Socra Harness
+Copyright 2026 MumpixDB. All rights reserved.
+
+The source code is made available under the Business Source License 1.1 in
+LICENSE. That license does not grant trademark rights.

package/README.md

@@ -0,0 +1,434 @@
+# wydcode
+
+Describe a bug at night; by morning there is a fix waiting that provably could
+not have touched your source tree. `wydcode` gives you a hash-pinned diff to review
+over coffee and promote with one command. The value is not "AI writes code"; a
+dozen tools do that. It is delegation without supervision: leave it alone, get a
+reviewable fix, and keep real writes behind a promotion gate.
+
+`wydcode` packages the Socra Harness engine behind a short npm command.
+
+`wydcode` is the public npm package and command. The implementation and some
+historical receipts still use the wydcode engine name, and `.socra/`
+remains the on-disk state directory.
+
+## License
+
+wydcode is source-available under the Business Source License 1.1 (BUSL-1.1).
+You may use it in production except to offer wydcode or wydcode to third
+parties as a commercial hosted service. Each version converts to Apache-2.0 on
+the earlier of its stated Change Date or four years after its first public BUSL
+distribution. This release's Change Date is 2030-07-09. See [LICENSE](LICENSE).
+
+## 90-Second Check
+
+Prerequisites:
+
+- Python `3.11+`
+- `git`
+- `node`
+- `npm`
+- internet access for first install and model pull
+- `ollama` if you use the Ollama commands below
+
+For the real-model check, also run an OpenAI-compatible local model endpoint.
+With Ollama:
+
+```bash
+# in another terminal, if Ollama is not already running
+ollama serve
+```
+
+Then:
+
+```bash
+ollama pull qwen2.5-coder:14b
+```
+
+Install `wydcode` from npm:
+
+```bash
+npm install -g wydcode
+wydcode --help
+```
+
+Or install from this checkout:
+
+```bash
+npm install -g .
+wydcode --help
+```
+
+Or install the Python package directly:
+
+```bash
+PYTHON="$(command -v python3.12 || command -v python3.11 || command -v python3)"
+"$PYTHON" - <<'PY'
+import sys
+if sys.version_info < (3, 11):
+    raise SystemExit("wydcode requires Python 3.11+. Install Python 3.11+ and rerun this block.")
+PY
+"$PYTHON" -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e .
+```
+
+Run the fixture loop:
+
+```bash
+python scripts/run_product_five_step_check.py \
+  --endpoint http://127.0.0.1:11434/v1 \
+  --model qwen2.5-coder:14b \
+  --receipt-scope local_workstation_smoke \
+  --keep-workdir
+```
+
+Expected shape:
+
+```text
+git init: exit=0
+git add: exit=0
+git commit fixture: exit=0
+wydcode init: exit=0
+wydcode fix: exit=0
+wydcode review: exit=0
+wydcode approve: exit=0
+wydcode promote: exit=0
+npm test real tree: exit=0
+receipt: .../docs/generated/product_five_step_check_latest.json
+wydcode_setup_under_five_minutes: True
+```
+
+The fixture starts with:
+
+```js
+export function add(a, b) {
+  return a - b;
+}
+```
+
+The promoted real tree should end with:
+
+```js
+export function add(a, b) {
+  return a + b;
+}
+```
+
+## Product Flow
+
+Initialize a git repo:
+
+```bash
+wydcode init \
+  --project ./my-repo \
+  --endpoint http://127.0.0.1:11434/v1 \
+  --model qwen2.5-coder:14b
+```
+
+Start a fix:
+
+```bash
+wydcode fix \
+  "In the updateLocale plugin, partial updates to nested locale formats wipe out sibling formats." \
+  --project ./my-repo \
+  --declared-file src/plugin/updateLocale/index.js
+```
+
+Review, then approve and promote or reject:
+
+```bash
+wydcode review --project ./my-repo
+wydcode approve --project ./my-repo
+wydcode promote --project ./my-repo
+# Or, when the staged patch is wrong:
+wydcode reject --project ./my-repo --reason "Held-out probe fails for nested arrays"
+```
+
+Important expected behavior:
+
+```text
+review  -> prints the exact dry-run diff and records hashes
+approve -> must be a separate command, bound to the presented diff hash
+reject  -> records a terminal human rejection for that hash and exports its trace
+promote -> the only product command that writes the real source tree
+```
+
+Every successful promotion, gate-rejected task attempt, and explicit human
+rejection appends a
+content-free trace to the local, cross-project ledger at
+`~/.wydcode/traces/events.jsonl`. MumpixDB maintains a
+rebuildable index of those traces; the hash-chained JSONL remains the source of
+truth. Inspect the growing fix journal or repair a missed export with:
+
+```bash
+wydcode traces status
+wydcode traces sync --project ./my-repo
+```
+
+`traces status` reports both indexed and pending event counts and exits nonzero
+while pending events exist. A trace is
+durable as soon as it reaches the hash-chained JSONL ledger, but it is not
+available in the rebuildable MumpixDB index until the pending count returns to
+zero. Exact recurrence routing reads and verifies the hash-chained source ledger
+directly; it does not trust approximate index results for route selection.
+`traces sync` exits nonzero when any index update remains incomplete.
+
+Trace records contain repository identity, task and model accounting, gate and
+artifact hashes, and changed-file paths. They do not contain source or patch
+content, and they never infer a recurrence family during collection.
+
+### Exact Recurrence Retrieval
+
+Retrieval is exact-or-abstain. It never uses embeddings, model relevance
+scores, thresholds, nearest neighbors, or approximate fallback. A fix opts in
+with a structured card compiled under the frozen four-field grammar:
+
+```bash
+wydcode fix \
+  "A later instance violates the same terminal-state invariant" \
+  --project ./my-repo \
+  --declared-file src/state.js \
+  --recurrence-card recurrence-card.json
+```
+
+After reading a passing diff, a reviewer may bind behavior rather than source
+or patch text. Minting also requires a passing held-out evidence artifact with
+hidden feedback disabled:
+
+```bash
+wydcode approve \
+  --project ./my-repo \
+  --behavior-card behavior-preference.json \
+  --heldout-evidence heldout-evidence.json
+wydcode promote --project ./my-repo
+```
+
+The promotion mints a probationary project-scoped `PREFER` gene only when the
+task gate, full-suite milestone, held-out probe, human authorization, bundle
+hash, repository identity, and exact key all agree. A later task fires only
+when exactly one prior gene has the same complete key. Missing keys, collisions,
+project mismatches, and exact task replays abstain.
+Injection also abstains unless the configured context budget preserves the full
+output cap, the existing prompt, and a fixed safety margin; retrieval never
+borrows output headroom.
+
+For a paired cold control, create the same frozen task in an isolated checkout
+with `--retrieval disabled`. A route fire or retrieval-backed promotion is not
+by itself a capability lift; that claim requires the gene-backed arm to pass
+where its paired cold arm fails under the same budgets and gates.
+
+Examples: [recurrence card](examples/exact-recurrence-card.json),
+[behavior card](examples/behavior-preference-card.json), and
+[held-out evidence](examples/heldout-gene-evidence.json). Existing traces that
+predate this mechanism are not retroactively enriched or treated as genes.
+
+### Large-file output contract
+
+For a single existing file whose estimated full replacement would consume at
+least 75% of the reserved output budget, wydcode automatically requests exact
+anchored edits instead of a full-file rewrite. Every anchor must match the
+original file exactly once, edit ranges may not overlap, and paths must remain
+inside the declared file set. Missing, repeated, overlapping, mixed-contract,
+or otherwise malformed anchors fail closed before an artifact reaches the test
+overlay. The harness then materializes accepted edits into the same atomic
+sandbox and runs the ordinary syntax, test, review, approval, and promotion
+gates; anchored mode does not bypass or weaken any gate.
+
+Gate outcomes distinguish a patch failure from a gate that could not execute.
+A syntax or test failure is evidence against the patch. A missing parser,
+compiler, test runner, or dependency is reported as infrastructure unavailable
+and blocks the task without classifying the patch as bad.
+
+Plan-only smoke without a live model:
+
+```bash
+wydcode fix \
+  "Fix add so it returns the sum" \
+  --project ./my-repo \
+  --declared-file src/math.js \
+  --plan-only
+```
+
+## How To Delegate Well
+
+Good bug descriptions name the area, plugin, file, function, or error surface.
+This helps `wydcode` choose a narrow first scope or fail closed.
+
+Better:
+
+```text
+In the updateLocale plugin, partial updates to nested locale formats wipe out sibling formats.
+```
+
+Also good:
+
+```text
+processValue appears to turn --timestamp into NaN before applyCoercions can run.
+```
+
+Weak:
+
+```text
+It breaks when I pass a timestamp.
+```
+
+If `wydcode` cannot determine a safe file scope, it stops and asks for
+`--declared-file`. That is intentional. Failing closed is a product feature;
+guessing wrong is a bug.
+
+## Model Expectations
+
+Small local models can be useful behind the gate, but they are not magic. In our
+receipts, `qwen2.5-coder:14b` handled small local JavaScript fixes and failed on
+a real TypeScript library by returning advice instead of a patch. The gate kept
+that failure out of the source tree.
+
+Use a stronger model when the repo is large, TypeScript-heavy, cross-file, or
+semantically subtle. `wydcode`'s job is to make the attempt auditable and gated, not
+to pretend every model can fix every bug.
+
+## Safety Model
+
+`wydcode` is a workspace tool, not a security sandbox.
+
+- The model can see the source files included in its prompt.
+- The model writes staged artifacts under `.socra/`.
+- Product source writes require `review -> approve -> promote`.
+- A reviewed patch can instead end with `reject`; that exact artifact hash can
+  never be approved afterward.
+- Approval is hash-bound to the exact presented diff.
+- `fix` requires the configured local endpoint to be reachable before creating a
+  real job.
+- Hosted fallback is disabled in the generated config.
+- Do not run `wydcode` on repositories containing secrets you would not show to the
+  configured model endpoint.
+
+See [SECURITY.md](SECURITY.md).
+
+## Receipts
+
+These are append-only evidence, not marketing claims.
+
+| Run | Date | Model | Outcome | Lesson |
+| --- | --- | --- | --- | --- |
+| Clean VM exit test | 2026-07-09 | `qwen2.5-coder:14b` | pass | setup and the five-step loop worked on a fresh Ubuntu VM |
+| Day.js real-repo exam | 2026-07-06 | `ornith-1.0-35b-Q6_K` | 3/5 clean primary passes | even a 35B local model has a real envelope |
+| Overnight Day.js run | 2026-07-09 | `qwen2.5-coder:14b` | `human_rejects_diff` | the gate caught a plausible task-green but semantically unsafe fix |
+| Cold yargs run | 2026-07-09 | `qwen2.5-coder:14b` | `bad_fix_gate_red`, subtype `not_a_patch` | advisory prose died at static review before tests or source writes |
+| Scope inference rerun | 2026-07-09 | `qwen2.5-coder:14b` | scope fixed, patch still rejected | inference improved; model quality remained bounded |
+| Acquisition false-negative audit | 2026-07-12 | `ornith-1.0-35b-Q6_K` | frozen `0/10`; repaired tail `4/5` promoted | failure-layer bucketing found a deterministic newline defect in Wydcode, not a pure model ceiling |
+
+Receipt index:
+
+- [Generated receipts](docs/generated/README.md)
+- [Public package rehearsal](docs/generated/wydcode_public_rehearsal_20260710.json)
+- [Public full-loop rehearsal](docs/generated/wydcode_full_loop_rehearsal_20260710.json)
+- [Registry action receipt](docs/generated/wydcode_registry_action_20260710.json)
+- [Clean VM exit test](docs/generated/clean_machine_exit_test_lima_qwen_20260709.json)
+- [Overnight Day.js result](docs/generated/overnight_real_repo_run_v1_result.json)
+- [Cold real-issue VM result](docs/generated/cold_real_issue_vm_run_v1_result.json)
+- [Scope inference rerun receipt](docs/generated/scope_inference_after_overnight_arm_a.json)
+- [Frozen acquisition result](docs/generated/ornith35b_acquisition_stopping_result_v1_20260712.json)
+- [Repaired acquisition-tail result](docs/generated/wydcode_final_newline_repair_tail_replication_result_v1_20260712.json)
+- [Moment-to-Day.js transfer writeup](docs/stress_tests/moment_to_dayjs_transfer_writeup.md)
+- [Scope inference v1.1 spec](docs/SCOPE_INFERENCE_V1_1_SPEC.md)
+
+## Clean-Machine Exit Test
+
+On a fresh Ubuntu/Linux VM:
+
+```bash
+bash scripts/run_clean_machine_exit_test_ubuntu.sh
+```
+
+The script installs documented prerequisites when needed, starts Ollama, pulls
+`qwen2.5-coder:14b`, installs `wydcode` into a local venv, and runs the five-step
+fixture check with `receipt_scope=clean_machine_exit_test`.
+
+Timing is split into:
+
+- prerequisite setup: external tools and model acquisition
+- `wydcode` setup: install time plus `wydcode init`
+- fix loop: `fix -> review -> approve -> promote -> npm test`
+
+Only `wydcode` setup is the under-five-minute setup claim. Model pull and inference
+time are reported separately.
+
+## Stranger-Test Protocol
+
+This is the launch gate.
+
+- two people who have never seen the project
+- README only
+- no coaching, hints, or touching their machine
+- success means the fixture loop completes unassisted
+- every stall is copied verbatim as a docs bug
+- if either person stalls, patch docs and rerun with a fresh stranger
+- if both pass, launch
+
+## Pre-Launch Gate
+
+- The repository must be public before Show HN or stranger testing.
+- The npm metadata links must resolve publicly before the next public publish.
+- The two-stranger gate must pass before the launch post is published.
+
+## Source And Contributions
+
+The source is licensed under BUSL-1.1; see [LICENSE](LICENSE). The `wydcode`,
+wydcode, Socra, and MumpixDB names and logos are not licensed with the
+source; see [TRADEMARKS.md](TRADEMARKS.md).
+
+Security reports belong in the repository's private vulnerability-reporting
+form, not a public issue. External code contributions require the contributor
+terms described in [CONTRIBUTING.md](CONTRIBUTING.md) before merge.
+
+## Current Limits
+
+- v1 scope inference uses path and filename signals. v1.1 will add
+  content-token rarity matching; see [Scope Inference v1.1](docs/SCOPE_INFERENCE_V1_1_SPEC.md).
+- Historical receipts may mention `socra`, `wydcode`, or wydcode.
+  Those are the engine and pre-public-name labels; the public package and command
+  are `wydcode`.
+- The project is local-first. It assumes you control the endpoint you configure.
+
+## Additional Harness Tools
+
+Start an interactive local GGUF session:
+
+```bash
+wydcode start
+```
+
+Serve a GGUF through the local OpenAI-compatible endpoint:
+
+```bash
+wydcode serve \
+  --model ~/models/model.gguf \
+  --llama-server /path/to/llama-server \
+  --alias MyLocalCoder \
+  --port 11439
+```
+
+Benchmark a GGUF:
+
+```bash
+wydcode eval humaneval \
+  --model ~/models/model.gguf \
+  --llama-cli /path/to/llama-cli \
+  --tasks /path/to/humaneval.jsonl \
+  --mode socra
+```
+
+Scan a repo for repeatable candidates:
+
+```bash
+wydcode scan ./my-repo --out .socra/candidates.json
+```
+
+Show status:
+
+```bash
+wydcode status --project ./my-repo
+```

package/SECURITY.md

@@ -0,0 +1,64 @@
+# Security
+
+`wydcode` is a local workspace tool, not a security sandbox.
+
+The internal engine and historical receipts may still use the Socra Harness
+name. The public command and npm package are `wydcode`; `.socra/` remains the
+state directory.
+
+## What `wydcode` Does Protect
+
+- Source changes are staged under `.socra/` before promotion.
+- `review` presents a dry-run diff and records artifact hashes.
+- `approve` is a separate command and is bound to the presented diff hash.
+- `promote` is the only product command that writes the real source tree.
+- Generated config disables hosted fallback by default.
+- Validated-fix traces stay local under `~/.wydcode/traces` and contain hashes
+  and metadata, not source or patch content.
+
+## What `wydcode` Does Not Protect
+
+- It does not make an untrusted model safe.
+- It does not hide prompted source files from the configured model endpoint.
+- It does not prevent a malicious local endpoint from logging prompts.
+- It does not sandbox arbitrary dependency install scripts.
+- It does not replace git, backups, code review, or CI.
+
+## Safe Use
+
+- Run `wydcode` only in git repositories.
+- Start with small, module-scoped fixes.
+- Use `--declared-file` when you know the file.
+- Read the diff before approving it.
+- Do not run `wydcode` on repositories containing secrets you would not send to the
+  configured local endpoint.
+- Prefer disposable VMs or containers for unfamiliar repositories.
+
+## Network And Installs
+
+Product `fix` uses the endpoint recorded in `.socra/config.json`.
+
+The cross-project trace ledger and its MumpixDB index are local files. No trace
+upload or hosted fallback occurs. Set `WYDCODE_TRACE_HOME` to move the store to
+another local volume.
+
+The hash-chained JSONL ledger is authoritative; the MumpixDB index is derived.
+Treat a nonzero `wydcode traces status` pending count as an evidence-integrity
+failure and run `wydcode traces sync --project .` before relying on retrieval.
+The CLI surfaces index failures without rolling back an already-applied,
+hash-receipted promotion.
+
+Interactive sandbox commands are separate from product promotion. If you enable
+network or install access for interactive agents, keep it inside disposable
+sandbox workspaces and review outputs before copying anything into source.
+
+## Reporting
+
+Do not open a public issue for a suspected vulnerability or leaked credential.
+Use GitHub's private vulnerability-reporting form for this repository:
+
+https://github.com/mumpix/wydcode/security/advisories/new
+
+Include the affected version, reproduction steps, impact, and any suggested
+mitigation. If the report includes a credential, provide only enough of the
+value to identify it; never paste a complete live secret.

package/SOCRA_SOURCE.md

@@ -0,0 +1,36 @@
+# Socra Source Provenance
+
+This npm package is the `wydcode` public distribution of the Socra Harness
+engine. The public command and npm package are `wydcode`; the Python module and
+some historical receipts still use the `socra_harness` / Socra Harness engine
+name.
+
+Canonical source repository:
+
+```text
+https://github.com/mumpix/wydcode
+```
+
+The source tree location is the repository root. Provenance identity is the
+commit below; it never includes a builder-specific absolute path.
+
+Canonical source reference used for `wydcode@0.4.3`:
+
+```text
+bd6e4f2a51f24f8ffaf30c5976f82d7fae5040f9
+```
+
+Source status:
+
+```text
+clean
+```
+
+Policy:
+
+- Changes land in the canonical source tree first.
+- `wydcode` is the public npm install identity.
+- Changes should land in the canonical tree first, then this package should be
+  regenerated from a pinned commit with `scripts/build_wydcode_package.sh`.
+- Rehearsals for stranger-facing docs must use the public command name
+  `wydcode`, not only the internal `socra-harness` alias.

package/TRADEMARKS.md

@@ -0,0 +1,12 @@
+# Trademarks
+
+`wydcode`, Socra Harness, Socra, MumpixDB, their logos, and associated product
+branding are marks of MumpixDB.
+
+The software license does not grant permission to use these marks to identify,
+promote, or imply endorsement of a modified product or commercial service.
+Accurate, nominative references to the unmodified project are permitted.
+
+Forks must use distinct names and branding unless MumpixDB grants written
+permission. Nothing in this policy limits rights that cannot be restricted by
+applicable law.