@supersuit/transcript-md 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 (2026-10-05)
+
+Initial standalone transcript.md codec, schema, reader, local guarded revisions, annotations, historical citations, CLI, and Python companion. Explicit caller roots work without a Freedom installation.
+
+Candidate corrections preserve configured Git hooks/signing, align native readiness receipts with the executed working directory, guard direct reader probes, and remove an unverified phone example from public source comments.

package/FORMAT.md

@@ -0,0 +1,23 @@
+# Transcript.md format, version 1
+
+A canonical record is `<record-id>/transcript.md`. Its UTF-8 header has LF `---` delimiters and one top-level snake_case key per line followed by a compact JSON value: valid YAML with exact JSON types. Strict decoding rejects duplicate keys (including nested keys), non-JSON values, prototype keys, malformed delimiters and invalid UTF-8. Body bytes are preserved independently of header serialization.
+
+Required header keys: `schema_version`, `kind`, `id`, `title`, `description`, `read_when`, `date`, `start`, `as_of`, `audience`, `keep`, `participants`, `sources`, `connections`, `aliases`, `review`, `body_format`, `legacy`, `extensions`. Schema version is integer1, kind conversation, body_format turns-v1 or legacy. Unknown facts use null/unknown with diagnostics; new records require an explicit audience. The packaged JSON schema and shared validator define exact nested fields. Unknown keys fail except declared extensions.
+
+Ids are stable, portable NFC directory components, with full default Unicode case-fold collision checks. New ids are lowercase kebab case. Participant ids, capture ids and turn ids are separate; person references never follow a label guess. Source Capture locators are bundled, external-local or service references; availability and backup are explicit facts. Bundled paths may not escape their entry or traverse symlinks. Date is a calendar day; instants require an RFC3339 zone. Clock-looking speech is never timing evidence.
+
+The body owns these exact H2 sections in order: `## Now`, `## Transcript`, `## Log`, `## Open questions`. Optional H1 title must match the header. Transcript turns use `### t-000001` followed immediately by `<!-- turn {JSON} -->` with exactly `speaker`, `sources`, `timing`, `source_gap`. Utterances remain exact bytes. Sources select capture+locator and explicit start/end spans; timing is null or capture, conversation with piecewise mappings, or wall-clock with explicit mappings. Unknown spans and source gaps remain visible.
+
+Reader APIs preserve original legacy header/body bytes and normalize safely readable metadata without writing. Enumeration admits direct flat legacy `.md` files and immediate canonical entries, excludes operational/attachment/annotation files, reports ambiguous ids/aliases and unclassified Markdown, and never follows symlinks. Redirects use only `{schema_version:1,kind:"conversation-redirect",to:<root-relative entry>}` and empty body; explicit-root resolution bounds hops and rejects escapes/loops.
+
+A Citation carries repository|null, original path, record_id, revision `{kind:"sha256"|"git",value}`, selector and exact sources. Turn selectors retain ordered ids and selected-text SHA; line selectors retain physical inclusive lines and selected-text SHA. Resolve through exact retained bytes, never HEAD or a current-file substitute. Seek uses only declared capture mappings and reports gaps, overlap and partial coverage.
+
+Creation spec: `{header,body,assets:[{relativePath,fromPath,sha256}],annotations:string|null}`. Assets are copied only when explicitly supplied and pinned; original assets remain.
+
+Annotation spec: `{markdown,citations,processing:"processed"|null,log:{date,text,evidence}}`, optionally `expected_annotations_sha256` (SHA or null expected absence). Annotations are separate generated interpretation.
+
+Revision spec: `{schema_version:1,revision_id,base_sha256,mode:"routine"|"deliberate-transcript-revision",authorization:null|{decision,base_sha256,turn_ids},operations,log}`. Revision id is a unique 8–128 character safe token reused only for exact retries; log has actual day, nonempty text and explicit evidence. Operations: `retitle`, `map-participant`, `add-participant`, `add-capture`, `add-capture-locator`, `append-turns`, `revise-turns`, `retire-turns`, with exact discriminated fields validated by the shared writer. Revision cannot arbitrarily replace date, sharing, record identity, legacy bytes or original capture identity. Deliberate reviewed-speech changes require operator-decision evidence and the exact sorted affected protected turns. Retirements preserve original versions and carry their protection to replacement turns.
+
+Complete revision journals retain exact pre/postimages, spec/hash, protection images, source pins, review transitions and Log before replacement. Recovery refuses third-state bytes. Stale expected SHA, reused revision with a different spec, an older retry after a later journal, unresolved historic human-review coverage, or changed protected baselines refuse. Read validation never fabricates human review.
+
+Sharing scope home/unknown grants no public projection; family requires the actual authorized group; share requires a stored explicit decision. Audience and generated interpretation cannot expand that boundary. Provider capture and bulk legacy migration are outside this package.

package/LICENSE

@@ -0,0 +1,45 @@
+Freedom
+Copyright (c) 2026 Continental Works. All rights reserved.
+
+This software and its accompanying files (the "Software") are the proprietary
+property of Continental Works. Access to this repository is granted to named
+individuals for the purpose of running Freedom on their own machines and
+contributing improvements back to Continental Works.
+
+You may:
+
+- run the Software on machines you control;
+- modify it for your own use;
+- submit modifications to Continental Works as pull requests or issues.
+
+You may not, without prior written permission from Continental Works:
+
+- redistribute the Software or any substantial part of it, in source or
+  binary form, to anyone who has not been granted access by Continental Works;
+- publish it, in whole or in part, in any public repository or package;
+- sell, sublicense, or offer the Software as a product or service to others;
+- remove or alter this notice.
+
+Contributions. By submitting a pull request, patch, or other modification to
+Continental Works, you grant Continental Works a perpetual, worldwide,
+irrevocable, royalty-free license to use, reproduce, modify, distribute, and
+sublicense that contribution as part of the Software, and you confirm that you
+have the right to grant it.
+
+That license is non-exclusive. You keep ownership of what you contribute and
+every right to use it however you like, in Freedom or anywhere else. Once
+Continental Works ships your contribution, you receive it back as part of the
+Software under these same terms, like everyone else running Freedom.
+
+Every pull request confirms this grant with the ticked Licensing line in its
+description (.github/pull_request_template.md). A pull request without it is
+not merged, and none of its code is used.
+
+Your own files stay yours. This license covers the Software only. The workspace
+you build with it (your people, projects, documents, transcripts, and every
+other file Freedom keeps for you) is yours, and nothing here claims any right
+to it.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL CONTINENTAL WORKS BE LIABLE FOR ANY CLAIM, DAMAGES,
+OR OTHER LIABILITY ARISING FROM THE USE OF THE SOFTWARE.

package/NOTICE

@@ -0,0 +1,43 @@
+transcript.md is extracted from Freedom.
+Copyright (c) 2026 Continental Works. All rights reserved.
+Source component: 7db9bdc729712c7487781bfe44850e90eedb6364.
+The original LICENSE is retained verbatim. This package is not MIT licensed.
+No third-party npm runtime dependencies are bundled.
+
+The Unicode case-folding data has the following retained notice (also in its source):
+
+Copyright © 1991-2026 Unicode, Inc.
+
+NOTICE TO USER: Carefully read the following legal agreement. BY
+DOWNLOADING, INSTALLING, COPYING OR OTHERWISE USING DATA FILES, AND/OR
+SOFTWARE, YOU UNEQUIVOCALLY ACCEPT, AND AGREE TO BE BOUND BY, ALL OF THE
+TERMS AND CONDITIONS OF THIS AGREEMENT. IF YOU DO NOT AGREE, DO NOT
+DOWNLOAD, INSTALL, COPY, DISTRIBUTE OR USE THE DATA FILES OR SOFTWARE.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of data files and any associated documentation (the "Data Files") or
+software and any associated documentation (the "Software") to deal in the
+Data Files or Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, and/or sell
+copies of the Data Files or Software, and to permit persons to whom the
+Data Files or Software are furnished to do so, provided that either (a)
+this copyright and permission notice appear with all copies of the Data
+Files or Software, or (b) this copyright and permission notice appear in
+associated Documentation.
+
+THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF
+THIRD PARTY RIGHTS.
+
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE
+BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES,
+OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE DATA
+FILES OR SOFTWARE.
+
+Except as contained in this notice, the name of a copyright holder shall
+not be used in advertising or otherwise to promote the sale, use or other
+dealings in these Data Files or Software without prior written
+authorization of the copyright holder.

package/README.md

@@ -0,0 +1,88 @@
+# @supersuit/transcript-md
+
+Local transcript.md conversation records: lossless structured headers, strict validation, read-only legacy interpretation, append-only annotations, expected-SHA revisions, persistent human-review protection, and immutable source citations.
+
+Requires Node 22 or newer. The Python companion requires Python 3.9 or newer and Node on PATH. Mutations additionally require Git 2.31 or newer and POSIX `ps`. Supported platforms are Linux and macOS. No runtime npm dependency, activation, account discovery, install hook, network capture, or global Freedom installation is required.
+
+```sh
+npm install @supersuit/transcript-md
+```
+
+The source repository stays private. The package carries the original Continental Works proprietary license and Unicode notice; npm availability does not grant MIT rights. Read [LICENSE](LICENSE) and [NOTICE](NOTICE).
+
+## JavaScript
+
+Save this as `example.mjs` in your consumer directory and run `node example.mjs`. It creates one synthetic record under your explicit local root and prints its unchanged speech. Running it again is an exact create retry.
+
+```js
+import {mkdirSync} from 'node:fs';
+import {resolve} from 'node:path';
+import {createConversation,readConversation,citeConversation} from '@supersuit/transcript-md';
+const root=resolve('./records');
+mkdirSync(root,{recursive:true});
+const header={schema_version:1,kind:'conversation',id:'example-call',title:'Example call',description:null,read_when:[],date:null,start:null,as_of:'2026-10-05',audience:'local',keep:{scope:'home',group:null,decision:null},participants:[],sources:[],connections:[],aliases:[],review:{transcription:'unreviewed',attribution:'unreviewed',processing:'unprocessed',evidence:[]},body_format:'turns-v1',legacy:null,extensions:{}};
+const metadata={speaker:null,sources:[],timing:null,source_gap:'Original capture unavailable.'};
+const body='\n## Now\n\n## Transcript\n\n### t-000001\n<!-- turn '+JSON.stringify(metadata)+' -->\nExact example words.\n\n## Log\n\n## Open questions\n';
+const created=createConversation({root,spec:{header,body,assets:[],annotations:null},pid:process.pid,by:'example'});
+const record=readConversation(created.path,{root});
+const citation=citeConversation(record,{turnIds:['t-000001']});
+console.log(JSON.stringify({path:record.file,text:record.turns[0].text.toString('utf8'),citation}));
+```
+
+Warnings identify genuinely unknown source, speaker, date and timing facts. They never invent those facts. The codec preserves body bytes, including CRLF, Unicode and the final newline state.
+
+## CLI
+
+These commands use the record from the JavaScript example. `transcript-md` is also available through your installed local bin directory.
+
+```sh
+./node_modules/.bin/transcript-md --help
+./node_modules/.bin/transcript-md list --workspace ./records --json
+./node_modules/.bin/transcript-md read ./records/meeting-transcripts/example-call/transcript.md --include-body --json
+./node_modules/.bin/transcript-md validate ./records/meeting-transcripts/example-call/transcript.md --json
+./node_modules/.bin/transcript-md sources ./records/meeting-transcripts/example-call/transcript.md --json
+./node_modules/.bin/transcript-md cite ./records/meeting-transcripts/example-call/transcript.md --turn t-000001 --json
+```
+
+Commands: `list`, `read`, `validate`, `sources`, `resolve`, `cite`, `seek`, `create`, `annotate`, `revise`, `recover`. Help lists the exact flags. `--capabilities --json` is versioned. Exit codes: 0 success, 1 missing record/no seek candidate, 2 invalid/incomplete, 3 stale pin/lock/collision, 4 privacy refusal. Help and capabilities do no root/config discovery.
+
+## Python companion
+
+Discover the explicit installed asset with `node -p 'require.resolve("@supersuit/transcript-md/python")'`. Pass that path as argument 1 and `./records` as argument 2 to `python3 -B -I -S example.py`. Save this as `example.py`:
+
+```python
+import importlib.util
+import json
+import sys
+from pathlib import Path
+spec=importlib.util.spec_from_file_location('freedom_conversations',sys.argv[1])
+records=importlib.util.module_from_spec(spec)
+spec.loader.exec_module(records)
+root=Path(sys.argv[2]).resolve()
+record=records.read_record(root/'meeting-transcripts/example-call/transcript.md',workspace=root,include_body=True)
+print(json.dumps({'id':record['id'],'text':record['turns'][0]['text']}))
+```
+
+The companion exposes `ConversationError`, `list_records`, `read_record`, `read_source_refs`, `annotate_record`, `revise_record`, and `recover_revision`. It invokes the adjacent packaged JavaScript CLI after capability checks. It never parses Markdown itself or consults a global resolver. Node/CLI failures retain diagnostics and nonzero exits through `ConversationError`.
+
+## Roots, journals and review safety
+
+Use `root` in JavaScript mutation options and `--workspace` in CLI calls. `listConversationDirectory(dir)` and CLI `list --transcripts-dir dir` take an already resolved transcript directory. The default transcript folder is `meeting-transcripts`. An optional caller-owned `.freedom.json` may map `paths.transcripts`, `paths.state`, `paths.people`, `paths.self`, and `paths.user` to explicit relative or absolute paths; `~` is rejected. No home config or inherited Freedom root is consulted. File-only mutation may find a local `.freedom.json` ancestor; provide `root` for an ordinary directory without that marker.
+
+Git journals are mode 0600 under the actual common Git directory's `freedom-conversation-revisions/`. Non-Git journals use `.agents/state/conversation-revisions` (or explicit mapped state) and report `transcript-root-only` scope. The common Git mutation lock and shared capture lock serialize writers across worktrees; relative state belongs to the main checkout. Caller-owned external mapped paths remain caller responsibility. Readers do not acquire locks, probe media or write files.
+
+`reviseConversation({file,root,spec,expectedSha,pid,by})` accepts the existing discriminated revision operations in [FORMAT.md](FORMAT.md), never an arbitrary patch. Pin the complete current file hash and the same `spec.base_sha256`. Human-reviewed speech remains protected after later append or review downgrade; changes require a deliberate authorization for the exact affected turn set. `recoverConversationRevision` only resumes or reverses an owned journal's exact pre/postimages and refuses third-state edits. No automatic Git commit is made.
+
+`annotateConversation` appends interpretation separately from speech. Its spec is `{markdown,citations,processing,log}` with optional `expected_annotations_sha256` (null means expected absence); use that extra pin when acting from an interpretation snapshot. Citation authenticity does not prove current sidecar freshness. `resolveConversationCitation({file,root,citation})` reads retained SHA history through the shared local journal; generic `resolveCitation` takes an explicit exact-version loader for Git or SHA history. Original paths, revision ids and selected-text hashes stay immutable. Sharing checks never infer publication permission from audience.
+
+## Explicit exports
+
+The root exports the unchanged codec, reader, writer and citation functions. Subpaths: `/codec`, `/reader`, `/writer`, `/citations`, `/schema` (JSON), `/python` (asset), `/cli` (executable asset). Internal context, lock and deployment modules are not exported.
+
+This package excludes provider/account capture, Granola conversion, operational project/person processing, bulk archive migration, runtime deployment, pilot and backup rollout. Legacy reads retain bytes and honest unsupported diagnostics; they are not a safe legacy conversion/apply engine.
+
+## Candidate verification and releases
+
+From the private source checkout, `npm ci --ignore-scripts` then `npm test`. `node scripts/run-tests.mjs --candidate` packs once, audits exact bytes, installs that tarball in an external clean consumer, and runs the README and installed safety checks. `node scripts/run-tests.mjs --installed CONSUMER` repeats the installed boundary with prospective physical readiness. Test fixtures and journals are external; HOME, Git identity, configured hooks and signing are preserved. Native receipts validate and execute the same physical working directory; direct reader probes also require fresh readiness. The payload audit rejects complete international phone-number examples. The first macOS default runtime follows the selected Xcode interpreter; `PYTHON` may select an explicit interpreter.
+
+CI exercises actual Linux with minimum Node 22.0.0/Python 3.9 and current Node 24/Python 3.13. The separate `publish.yml` workflow is triggered only by a matching `v<version>` tag, tests and installs its audited tarball first, and publishes those same bytes through GitHub Actions OIDC. Repository history stays private. The first npm package/trusted-publisher prerequisite remains an external release gate; candidate CI does not publish.

package/index.mjs

@@ -0,0 +1,4 @@
+export * from './lib/frontmatter/conversation.mjs';
+export * from './lib/freedom-conversations.mjs';
+export * from './lib/freedom-conversation-write.mjs';
+export * from './lib/freedom-conversation-citations.mjs';