fix(release): verify candidate lineage before PyPI publish; docs: portfolio README template

[hseshadr]

Post-0.4.3 follow-ups. Two commits: the fix first, then the README.

1. Publish lineage (ca46767)

publish.yml published the workflow_run artifact gated only on workflow_run.head_branch == default_branch. A dispatch of release-candidate.yml on a tag named main passes that check.

This mirrors privacy-core's fix. A new first step, "Verify the candidate's lineage", runs before any artifact is touched and takes its inputs only as quoted env values under set -euo pipefail. It checks two things:

• gh api …/actions/runs/$RUN_ID | jq -e: the triggering run must be a completed, successful workflow_dispatch of .github/workflows/release-candidate.yml in this repository (base and head), with head_sha == HEAD_SHA.
• compare/$HEAD_SHA...$GITHUB_SHA must be ahead or identical.

The filename stays publish.yml, because PyPI trusted publishing is bound to it; a header comment now says so.

tests/test_workflow_security.py pins the step, its env, every jq clause, the reachability check and the filename. The old shell-free assertion now allows exactly this one shell step.

Evidence:

• Red first: 11 tests failed on the old workflow.
• Mutation: deleting the compare lines fails test_should_require_head_sha_to_be_reachable_from_the_default_branch.
• Behaviour: I ran the extracted script locally with a fake gh. It accepts ahead and identical. It refuses diverged (the tag-named-main case), another workflow path, a push event and a different sha.

Problem Details / toJSON: already covered, so no change. toJSON is in _RESERVED_PROBLEM_MEMBERS, and removing it fails test_should_never_emit_a_prototype_sensitive_key_even_with_a_scalar_value[toJSON].

2. README template (e13bba2)

• Tagline (also the pyproject description, 116 chars): Keeps each customer's search results apart in a shared vector index, and gives errors stable codes, for Python apps.
• Hero and Try it in 60 seconds: real output of a 15-line example. I ran it in a fresh folder against edgeproc-core==0.4.3 from PyPI:
  • acme and globex store identical vectors, forced into one index with num_buckets=1. Searching as acme returns [('acme-invoice', 0.0)].
  • define_errors(starter_pack).classify({"status": 402}) gives {'type': 'ai.provider.out_of_credits', 'title': 'Your provider account is out of credits. Add credits and try again.', 'status': 402}.
• Status: Beta at v0.4.3. The classifier moves to 4 - Beta; the published 0.4.3 metadata is unchanged.
• Layout: the architecture-map link is added, and the deep content stays below the fold.
• Tests: new tests/test_readme_contract.py runs inside uv run poe gate. The quickstart-ordering docs test now targets the new headings.
• Unchanged checks, all passing: source-pin, coverage-claim (99.31%), benchmark-figure and docs-imports.
• CHANGELOG [Unreleased] has entries for both commits.

Local: uv run poe gate green (366 passed, 99.31% coverage).

Owner actions, not done here:

• Set the GitHub "About" description to the same tagline.
• pypi-attestations verify could not be run from this sandbox because TUF refresh is blocked. The integrity endpoint does return 200 for the 0.4.3 wheel.

🤖 Generated with Claude Code

https://claude.ai/code/session_01N5FAenn7CZm8tswqWR9PjJ

---

Generated by Claude Code