Restore the example notebooks, and refresh the brand assets - #3
Merged
Conversation
`olaf_cookbook` shipped with 3 code cells and `olaf_master_workflow` with 3.
They had 32 and 14 before commit 8ffbe8b ("chore: integrate public v1
groundwork") replaced both with inert scaffolds during release preparation.
Nothing required that. Running the release gate against the pre-strip content
returns PASS with zero findings: the examples use synthetic GUIDs, contoso.com
addresses, no stored outputs, and no real identifiers of any kind. The
published repository was simply missing the material that makes it usable —
every worked example in the cookbook, and the runnable stage-by-stage pipeline
the master workflow exists to be.
Restored, but ported rather than reverted: the pre-strip notebooks predate the
omission-candidate contract and the provenance redesign, so a verbatim revert
would have reintroduced retired vocabulary the rest of the tree no longer uses.
Two of those were live code, not prose:
- `olaf_master_workflow` read `done.get("deleted")` from the apply envelope.
That key is now `omitted_role_candidates`, so the cell printed "deleted 0"
on every run no matter what the payload left out.
- Its `role_actions` helper sorted on `order = {"delete": 0, ...}`. The runtime
emits `omit`, never `delete`, so omitted roles fell to the default rank and
sorted last under a heading that promised them first.
The Run-All guard the strip introduced is kept on the cookbook. It was the one
good idea in that change; deleting 32 example cells to get it was not. The
master workflow keeps its own `auto_approve = False` gate instead, which is
what it always used, and does not get an unconditional exit — a pipeline
notebook that cannot run is not a pipeline notebook.
Brand assets refreshed in the same change:
- The lockups become the new light/dark banners (1280 x 640).
- The social preview becomes the card carrying the wordmark, the project name
and the plan -> review -> apply sequence, replacing a text-free composition
of the logo alone. A shared link now says what the project is without the
reader opening it.
- PROVENANCE.md records the new hashes and dimensions, and no longer states
that the social preview "contains no text" — true of its predecessor, false
of this one the moment the file changed.
Gates: lint clean, 1657 tests, release gate 0 findings, every PROVENANCE hash
re-verified against the file on disk. The pinned Gitleaks scan needs a
container runtime and runs in CI.
The same commit that gutted the notebooks (8ffbe8b) rewrote README.md whole, dropping eight sections. Two of them are the ones a newcomer needs first: - **What is OneLake security?** — the technology this project exists to operate, with the five official Microsoft references. Every claim in it was re-checked against the current build: `BLANK` is still in the supported RLS operator set, rule C9 still exists, and all five links resolve. - **Why OLAF?** — what the framework adds on top of that enforcement layer. One line was ported: `plan` shows what will be "created, updated, or omitted from the submitted payload", not "removed". **Status was NOT restored, deliberately.** It claimed "Verified on a live Fabric workspace ... enforcement confirmed from a Viewer seat". The README now says the opposite two sections down — "does not claim live verification" — and that is the accurate one. It was removed for a good reason. Roadmap is back as a checklist, rewritten rather than restored: the old one listed three items and docs/roadmap.md now carries five. Added the fifth as a new roadmap entry — a local authoring tool that validates and builds a config against a real workspace from a developer machine. It is planned, not built, and the entry says what actually blocks it: a Fabric token and real principal identifiers leaving the Fabric boundary for a laptop, where a local cache, shell history, editor undo file and crash dump are all places they land by default. Validation only; it must never grow a second write path. Layout: the CAUTION block moves out of the masthead into "Before you start", where its instruction (complete the external access review before uploading a real workbook) is actually actionable. IMPORTANT stays at the top, shortened — it is positioning, not an operating warning, and burying it would contradict the posture the rest of the project keeps. Badges: a second row for what CI proves and what it runs on — coverage (labelled "fixtures", because that is what the number measures), the release tag, Python 3.11/3.12/3.13, Fabric Runtime 1.3 / Spark 3.5+, hash-pinned dependencies, ruff. The ruff badge is unlinked: linking astral.sh would have needed a new entry in the release gate's evidence-host allowlist, and that allowlist is a control, not a convenience. No version number is hardcoded in README prose any more. The release badge reads the tag, so a release no longer needs a README edit to stay true.
`8ffbe8b` dropped it along with the rest. Two files still describe `olaf-mascot.png` as the "README hero" — `docs/brand-guidelines.md:110` and `assets/brand/README.md:8` — while nothing in the README referenced it, so restoring the image makes those two lines true again rather than only satisfying a memory. Placed where the original had it, adjusted for the sections that changed around it: after the last content section, before the licence and the independent-project disclaimer. Artwork does not belong after the fine print. The alt text is rewritten rather than restored. The old one said the owl was "keeping watch over a notebook that carries the approval seal"; the artwork shows it holding the notebook, and what the notebook carries is the OLAF shield crest with its padlock. Someone reading the page with a screen reader should get the picture that is actually there. The caption ends "before it is submitted" rather than "before it lands" — what OLAF controls is the request it sends, which is the same distinction the omission-candidate contract draws everywhere else.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this fixes
olaf_cookbookships with 3 code cells andolaf_master_workflowwith 3. They had 32 and 14 before8ffbe8b("chore: integrate public v1 groundwork") replaced both with inert scaffolds during release preparation.Nothing required that. Running the release gate against the pre-strip content returns PASS, 0 findings — the examples use synthetic GUIDs,
contoso.comaddresses, no stored outputs, and no real identifiers. The published repository was simply missing the material that makes it usable: every worked example in the cookbook, and the runnable stage-by-stage pipeline the master workflow exists to be.olaf_cookbook.ipynbolaf_master_workflow.ipynbPorted, not reverted
The pre-strip notebooks predate the omission-candidate contract and the provenance redesign, so a verbatim revert would have reintroduced retired vocabulary. Two of those were live code, not prose:
olaf_master_workflowreaddone.get("deleted")from the apply envelope. That key is nowomitted_role_candidates, so the cell printeddeleted 0on every run regardless of what the payload actually left out.role_actionshelper sorted onorder = {"delete": 0, ...}. The runtime emitsomit, neverdelete, so omitted roles fell to the default rank and sorted last under a heading promising them first.Every
OLAF.*call in both notebooks was checked against the runtime's actual 41-name API surface: no unknown calls.Guards
The Run-All guard the strip introduced is kept on the cookbook — it was the one good idea in that change; deleting 32 example cells to get it was not. The master workflow keeps its own
auto_approve = Falsegate, which is what it always used, and deliberately does not get an unconditional exit: a pipeline notebook that cannot run is not a pipeline notebook.Brand assets
PROVENANCE.mdrecords the new hashes and dimensions, and no longer states the social preview "contains no text" — true of its predecessor, false of this one the moment the file changed.Verification
scripts/lint.shpytestcheck_public_release.py tree .The pinned Gitleaks scan needs a container runtime and runs in CI.