Skip to content

Publish verified security and native validation documentation #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JasonStys merged 3 commits into from
Nov 10, 2026
Merged

Publish verified security and native validation documentation #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7fc7693
docs: publish verified security and native validation editions
JasonStys Nov 10, 2026
801f485
Bound actual Office XML inflation and test understated ZIP sizes
JasonStys Nov 10, 2026
e2d0ad1
Merge accepted runtime and refresh independently reviewed CFS editions
JasonStys Nov 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitattributes
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,4 @@
# Worker resources must remain Linux-compatible even inside Windows/macOS installers.
runner/** text eol=lf
*.docx binary
*.xlsx binary
10 changes: 8 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,10 +38,10 @@ The [source inspection workflow](docs/source-navigation.md) explains stale/legac

## Run and install

The 0.4.1 source prepares a security hotfix. Its [release notes](docs/releases/v0.4.1.md)
Version 0.4.1 includes bounded worker-report reads and verified source review. Its [release notes](docs/releases/v0.4.1.md)
and [full-main finding/validation report](docs/reports/codeql-main-fixes-2026-11-09.md)
describe the bounded worker reader and the fresh native/download checks required
before publication. A source version change alone does not replace a published download.
before release promotion. Check Releases for the currently published downloads; a source version alone does not replace one.

For end users, use the checksummed OS-specific packages in Releases. The UI runtime is bundled. Open the app's **Code Flow → Open local website** menu for browser use; no login token appears in the URL. Compiler jobs require an isolated local Unix/named-pipe Docker engine and the trusted worker image. Missing isolation is blocked, never passed; there is no host-execution fallback. Save/edit/static review/history/help remain usable without Docker.

Expand Down Expand Up @@ -115,3 +115,9 @@ GitHub Actions `security-extended` analysis, review steps and unsupported scope.
The [dated scan report](docs/reports/codeql-2026-11-09.md) distinguishes actual results
from pending/missing evidence. Static scanning supplements the existing runtime,
dependency, privacy and isolation checks; it does not certify every input or platform.

## Documentation editions

Start with the [organized handbook](docs/handbook.md) for current usage, design, security and test guidance. Reviewed downloadable editions: [project-guide.docx](docs/reports/project-guide.docx) · [validation-review.docx](docs/reports/validation-review.docx) · [validation-evidence.xlsx](docs/reports/validation-evidence.xlsx).

[Publication identities and source scope](docs/reports/publications.json) · [Documentation validation record](docs/reports/documentation-refresh-2026-11-09.md). Historical results retain their own tested revision and date.
145 changes: 145 additions & 0 deletions docs/code-index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3216,6 +3216,151 @@ Generated declaration locations. Python uses AST; JS/TS uses declaration-line ma
| variable | `real` | 148 |
| parameter | `kwargs` | 150 |

## tests/test_publications.py

| Kind | Declaration | Line |
|---|---|---|
| variable | `FILES` | 29 |
| variable | `NS` | 30 |
| variable | `XML_BYTES` | 31 |
| function | `validate_publications(root)` | 34 |
| parameter | `root` | 34 |
| variable | `reports` | 36 |
| variable | `manifest` | 37 |
| variable | `source` | 38 |
| variable | `records` | 45 |
| variable | `r` | 46 |
| variable | `workflows` | 48 |
| variable | `r` | 49 |
| variable | `r` | 60 |
| variable | `record` | 63 |
| variable | `stream` | 66 |
| variable | `payload` | 67 |
| variable | `package` | 74 |
| variable | `members` | 75 |
| variable | `m` | 76 |
| variable | `names` | 76 |
| variable | `required` | 77 |
| variable | `m` | 85 |
| variable | `xml` | 87 |
| variable | `member` | 88 |
| variable | `lower` | 89 |
| variable | `marker` | 91 |
| variable | `xml_stream` | 101 |
| variable | `xml_bytes` | 102 |
| variable | `text` | 105 |
| variable | `marker` | 106 |
| variable | `relation` | 110 |
| variable | `approval` | 118 |
| variable | `count` | 119 |
| variable | `n` | 123 |
| variable | `name` | 127 |
| variable | `node` | 127 |
| variable | `tables` | 127 |
| variable | `t` | 131 |
| variable | `cells` | 134 |
| variable | `node` | 136 |
| variable | `c` | 137 |
| variable | `n` | 140 |
| variable | `row` | 141 |
| variable | `expected` | 142 |
| variable | `actual` | 148 |
| variable | `c` | 148 |
| function | `copy_publications(tmp_path)` | 153 |
| parameter | `tmp_path` | 153 |
| variable | `source` | 155 |
| variable | `target` | 156 |
| variable | `name` | 158 |
| function | `rewrite_package(root, filename, change)` | 163 |
| parameter | `change` | 163 |
| parameter | `filename` | 163 |
| parameter | `root` | 163 |
| variable | `path` | 165 |
| variable | `original` | 166 |
| variable | `entries` | 167 |
| variable | `m` | 167 |
| variable | `package` | 169 |
| variable | `content` | 170 |
| variable | `name` | 170 |
| variable | `manifest_path` | 172 |
| variable | `manifest` | 173 |
| variable | `r` | 174 |
| variable | `record` | 174 |
| variable | `payload` | 175 |
| function | `test_actual_reviewed_publications_are_bound_to_source_and_workflows()` | 181 |
| function | `test_actual_binary_tamper_fails_digest(tmp_path)` | 186 |
| parameter | `tmp_path` | 186 |
| variable | `root` | 188 |
| variable | `path` | 189 |
| function | `test_renamed_publication_cannot_select_an_external_path(tmp_path)` | 195 |
| parameter | `tmp_path` | 195 |
| variable | `root` | 197 |
| variable | `path` | 198 |
| variable | `record` | 199 |
| function | `test_rehashed_active_office_members_still_fail(tmp_path, member)` | 210 |
| parameter | `member` | 210 |
| parameter | `tmp_path` | 210 |
| variable | `root` | 212 |
| parameter | `entries` | 216 |
| function | `test_rehashed_zip_without_document_root_fails(tmp_path)` | 222 |
| parameter | `tmp_path` | 222 |
| variable | `root` | 224 |
| parameter | `entries` | 225 |
| function | `test_rehashed_workbook_missing_actual_filter_fails(tmp_path)` | 230 |
| parameter | `tmp_path` | 230 |
| variable | `root` | 232 |
| function | `remove_filter(entries)` | 234 |
| parameter | `entries` | 234 |
| variable | `n` | 236 |
| variable | `name` | 236 |
| variable | `table` | 237 |
| function | `test_rehashed_workbook_changed_formula_fails(tmp_path)` | 246 |
| parameter | `tmp_path` | 246 |
| variable | `root` | 248 |
| function | `change_formula(entries)` | 250 |
| parameter | `entries` | 250 |
| variable | `name` | 252 |
| variable | `sheet` | 253 |
| variable | `formula` | 254 |
| function | `test_dishonest_compressed_xml_uses_bounded_actual_decompression(tmp_path, monkeypatch)` | 263 |
| parameter | `monkeypatch` | 263 |
| parameter | `tmp_path` | 263 |
| variable | `root` | 265 |
| variable | `name` | 266 |
| parameter | `entries` | 268 |
| variable | `path` | 270 |
| variable | `payload` | 271 |
| variable | `end` | 272 |
| variable | `cursor` | 273 |
| variable | `changed` | 274 |
| variable | `comment_size` | 276 |
| variable | `extra_size` | 276 |
| variable | `filename_size` | 276 |
| variable | `filename` | 277 |
| variable | `local` | 279 |
| variable | `changed` | 283 |
| variable | `cursor` | 284 |
| variable | `manifest_path` | 287 |
| variable | `manifest` | 288 |
| variable | `r` | 289 |
| variable | `record` | 289 |
| variable | `limits` | 292 |
| variable | `factory` | 293 |
| class | `BoundedInflater` | 295 |
| function | `__init__(self, actual)` | 298 |
| parameter | `actual` | 298 |
| parameter | `self` | 298 |
| function | `decompress(self, data, max_length)` | 302 |
| parameter | `data` | 302 |
| parameter | `max_length` | 302 |
| parameter | `self` | 302 |
| function | `__getattr__(self, attribute)` | 309 |
| parameter | `attribute` | 309 |
| parameter | `self` | 309 |
| function | `observed_factory(compression)` | 313 |
| parameter | `compression` | 313 |
| variable | `actual` | 315 |

## tests/test_release.py

| Kind | Declaration | Line |
Expand Down
67 changes: 67 additions & 0 deletions docs/handbook.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# Code Flow Studio handbook

By Jason Stys.

Filter diagnostics, unused-code candidates and missed coverage; inspect hash-verified source and navigate safely to unchanged drafts. Fixed rapid typing, worker compatibility and native launch preparation.

Turns report findings into a reproducible developer triage workflow while preserving source identity and isolated execution.

## Read the documentation

| Edition | Audience and contents |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| [project-guide.docx](reports/project-guide.docx) | User and developer guide: purpose, current usage, design, boundaries and source references. |
| [validation-review.docx](reports/validation-review.docx) | Reviewer edition: exact tested baseline, observed workflows, dated local results and remaining limits. |
| [validation-evidence.xlsx](reports/validation-evidence.xlsx) | Two filterable Excel Tables for observed workflows and test-source inventory, with recalculating outcome formulas. |

The editable Markdown remains the maintenance source. The Word files are readable editions, and the workbook is an evidence index rather than a test runner. See [publication identities and review](reports/publications.json) and the [documentation refresh record](reports/documentation-refresh-2026-11-09.md).

## Current usage and help

[README quick start](../README.md) is the entry point. Use the project-specific guides below before changing inputs, operating modes or deployment assumptions.

### Usage and operations

- [release checklist v0.2](release-checklist-v0.2.md)
- [releases/v0.2.0](releases/v0.2.0.md)
- [releases/v0.2.1](releases/v0.2.1.md)
- [releases/v0.3.0](releases/v0.3.0.md)
- [releases/v0.4.0](releases/v0.4.0.md)
- [releases/v0.4.1](releases/v0.4.1.md)

### Design and contracts

- [adr polyglot evidence](adr-polyglot-evidence.md)
- [adr private local](adr-private-local.md)
- [architecture](architecture.md)
- [private api](private-api.md)
- [research](research.md)

### Security and validation

- [security](security.md)
- [test plan v0.2](test-plan-v0.2.md)
- [testing](testing.md)
- [validation locations](validation-locations.md)
- [validation polyglot](validation-polyglot.md)
- [validation v0.2](validation-v0.2.md)
- [validation](validation.md)

## Historical results and reproduction

The reviewed source is [`7d2158a57bb49e8f837fffbfe23b301902465412`](https://github.com/JasonStys/code-flow-studio/tree/7d2158a57bb49e8f837fffbfe23b301902465412). The observed functional workflow baseline is `7d2158a57bb49e8f837fffbfe23b301902465412`; those observations are recorded at `2026-11-10T13:28:55.865054+00:00`. They do not certify an unrun later revision.

- [Detailed recorded validation](reports/native-http-drain-2026-11-10.md)
- [Current Actions](https://github.com/JasonStys/code-flow-studio/actions) records later integration checks separately.
- Preserve dated measurements and follow the existing testing guide to reproduce them; a test-source inventory alone does not establish execution.

## Practical boundaries

- Local account/vault plaintext is accessible to the trusted local service and device OS while unlocked; this is not browser-only end-to-end encryption or public SaaS authentication.
- Compiler tests require the fixed isolated local worker image. No host-code fallback, automatic Docker repair, universal coverage/bug detection or hostile-code security certification is provided.
- The five-second HTTP drain is not a universal exit-time guarantee: critical disk/container cleanup and vault sealing must finish safely; preserve recovery data on failure.
- Supported CodeQL categories, actual statement coverage, fixture browser journeys and tiny CPU training have distinct scopes. Passing checks do not establish model quality, vulnerability freedom or clean-machine installer acceptance.

## Maintaining these editions

Update the editable usage/design/test documents first. Rebuild and visually review every Word page and workbook tab before replacing an edition; verify the exact binary digests and evidence source in publications.json. Keep account data, logs with secrets, installed-app state and private test stores out of documentation. Source and release assets retain their existing security and licensing boundaries.
19 changes: 18 additions & 1 deletion docs/releases/v0.4.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,26 @@
# Code Flow Studio 0.4.1 — bounded worker reports
# Code Flow Studio 0.4.1 — bounded reports and safe shutdown

By Jason Stys. This source prepares a hotfix; a new downloadable release requires
successful exact-source validation, full-main CodeQL review and three-OS native
package acceptance. Published 0.4.0 assets and tags remain unchanged.

The native account service gives HTTP work five seconds to drain, then cancels
and joins its own remaining request tasks before normal vault sealing. Real
offloaded disk operations and authorized local account/provider transitions finish
under the existing request mutex before cancellation is reported, including
repeated cancellation. Unlock/lock, provider destination/key/consent publication,
deletion, logout and recovery reset retain coherent local state. Request bodies,
AI calls and arbitrary network waits remain cancellable.

Actual native acceptance now requires numeric HTTP-drain observations, completed
workspace/lifespan/server/main milestones and absence of both owned service and
bootloader PIDs, as well as the existing account/editor/privacy/lock checks.
The [native-drain report](../reports/native-http-drain-2026-11-10.md) records the
real held-request, snapshot/restore and cancellation controls. The five-second
HTTP budget is not a universal process-exit guarantee: critical disk/container
cleanup must finish safely, and failed cleanup preserves recovery data. No force
exit, skipped sealing, test retry or increased native deadline is introduced.

The fixed JavaScript/TypeScript worker bridge opens each native JSON report once,
checks that descriptor's regular-file/size metadata, caps the bytes actually read
at eight MiB plus one sentinel byte, and closes it even on malformed JSON or I/O
Expand Down
56 changes: 56 additions & 0 deletions docs/reports/documentation-refresh-2026-11-09.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# Documentation refresh — 2026-11-09

By Jason Stys.

This documentation-only edition describes source `7d2158a57bb49e8f837fffbfe23b301902465412`. It does not change application behavior, accounts, private data, installers or published releases.

## Published editions and completed review

| File | Bytes | SHA-256 | Reviewed scope |
| ---------------------------------------------------- | ----: | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| [project-guide.docx](project-guide.docx) | 46007 | `4d0a998f70fb0d798a6a76e3739af62f54c73c4d147bc9ddbdf1f5f3bac0d039` | 6 pages, each individually viewed at original resolution |
| [validation-review.docx](validation-review.docx) | 47230 | `3e472c90824be2501e0acdc7aff2ea6750ca9f4f0109804d0ff97e74020ee973` | 6 pages, each individually viewed at original resolution |
| [validation-evidence.xlsx](validation-evidence.xlsx) | 7760 | `0a9b5f1e6239dcb400bf195887461fcc967eec545633d1ebf3280d3353356c71` | Both previews; two actual Tables/autoFilters, four formulas, 3/3/0/0 values and failure-toggle/restore verified |

Word review checked plain black titles, readable pagination, whole table rows, source references, practical limits and absence of clipping or overflow. Render receipts were matched to the current DOCX digest before approval. Workbook review inspected both tab previews and actual exported Table/autoFilter elements; recalculated success/failure summaries were compared independently with workflow metadata. Static previews do not draw Excel dropdown arrows; the exported workbook contains the actual filters.

## Evidence and change boundary

- Functional baseline: `7d2158a57bb49e8f837fffbfe23b301902465412`.
- Workflow observation: `2026-11-10T13:28:55.865054+00:00`; exact run URLs and source identities remain in [publications.json](publications.json).
- Local document-package validation verifies exact copied bytes, Office ZIP integrity, approved page/tab identities and internal documentation links. Repository-specific documentation and source-policy commands are run separately and recorded in the integration handoff.
- Source/index metadata is regenerated using the repository’s existing tools. Existing privacy, security, coverage and workflow gates are retained.
- PR and later main workflows must pass independently. This record does not claim future or unrun integration CI success.

## Interpretation

The Word files document the cited source; dated source reports retain their original execution scope. A passing workflow is distinct from completed analysis with zero findings, and neither establishes production suitability. The Excel source inventory is not a per-test execution report. Checksums identify exact bytes, not a signature or publisher attestation.

Use the [handbook](../handbook.md) to choose usage, design, security and test documentation. Keep editable Markdown and reviewed editions together; do not replace historical measurements with undated claims.

## Local integration checks and future CI

The runtime baseline above passed its full main workflows, actual full supported-language
CodeQL analysis and three-OS native acceptance. Final local documentation integration
passed 275 tests and 28 subtests in 48.49 seconds, measuring 1,539/1,808 controller/data
statements (85.12%, unchanged 80% floor). The ten publication cases include real
package tamper, closed filenames, macro/ActiveX/embedding rejection, missing Word
root, changed Excel filters/formulas and understated compressed XML sizes.

Actual XML inflation is bounded to an eight-MiB read plus one sentinel byte before
checking actual/declared length. The genuine zlib oracle rejects the former
unbounded reader before a large output request; later CRC rejection alone is not
a memory-bound proof. Development-only defusedxml 0.7.1 forbids DTDs, with no new
application runtime dependency, account schema or migration.

Ruff, 87 exact source maps, strict TypeScript/Vite production build, approved-byte/
ZIP/source/workflow/link validation and diff hygiene passed. The existing pytest
cache and large UI-chunk warnings remain visible. All twelve current Word pages
and both workbook previews were independently viewed at original resolution;
saved OOXML contains the two actual Tables/autoFilters, all 27 source-bound test
paths and four formulas with 3/3/0/0 cached results. The matching failure-change/
restore receipt was checked; native Excel recalculation is not claimed.

These are local integration observations. Fresh PR and final main workflows and
later draft/download/installer acceptance remain separate required gates. Existing
0.4.0 public assets, installed user apps and account stores are unchanged.
Loading
Loading