Promote filesystem R/W gaps and add mount-grade driver architecture

.github/cli-purge-fix.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+p = Path('Compression.CLI/Program.cs')
+t = p.read_text()
+old = '''    var before = ops.List(File.OpenRead(archive.FullName), null).Count(e => !e.IsDirectory);'''
+new = '''    int before;\n    using (var source = File.OpenRead(archive.FullName))\n      before = ops.List(source, null).Count(e => !e.IsDirectory);'''
+if old not in t:
+    raise SystemExit('generated purge read handle anchor not found')
+p.write_text(t.replace(old, new, 1))
+Path('.github/cli-purge-fix.py').unlink()

.github/coverage-matrix.py

@@ -0,0 +1,94 @@
+from pathlib import Path
+import re
+
+
+def scan(root):
+    rows=[]
+    for path in sorted(Path(root).glob('**/*FormatDescriptor.cs')):
+        text=path.read_text(errors='ignore')
+        cm=re.search(r'public\s+(?:sealed\s+)?class\s+\w+FormatDescriptor\s*:\s*(.*?)\{',text,re.S)
+        mid=re.search(r'public\s+string\s+Id\s*=>\s*"([^"]+)"',text)
+        if not cm or not mid: continue
+        interfaces=set(re.findall(r'\bI[A-Za-z0-9_]+\b',cm.group(1)))
+        tunable='FormatOptionKind.Boolean' in text or re.search(r'AllowedValues\s*:\s*\[[^\]]*,',text,re.S)
+        optimize=('ILayoutOptimizable' in interfaces or
+                  ('IFormatOptionsSchema' in interfaces and tunable and
+                   ('IArchiveCreatable' in interfaces or 'IStreamFormatOperations' in interfaces)))
+        row={
+          'id':mid.group(1), 'ifaces':interfaces,
+          'defrag':'IArchiveDefragmentable' in interfaces,
+          'shrink':'IArchiveShrinkable' in interfaces,
+          'wipe':'IWipeEmpty' in interfaces,
+          'purge':'IArchivePurgeable' in interfaces or 'IArchiveModifiable' in interfaces,
+          'optimize':optimize,
+          'meta':'IFileInternalLayoutMap' in interfaces or 'IFileInternalChunkMover' in interfaces,
+        }
+        row['compact']=row['defrag'] or row['shrink'] or row['optimize']
+        rows.append(row)
+    return rows
+
+
+def mark(v): return '✅' if v else '—'
+
+def fs_section(rows):
+    lines=[
+      '## Filesystem descriptors', '',
+      'Generated from the descriptor capability interfaces in this tree. **Compact** is the composite '
+      'defrag → optimize → shrink action and is available when at least one of those primitives is executable. '
+      'A checkmark may represent a native in-place operation or a verified offline rebuild; mounted-driver R/W '
+      'is tracked separately by the filesystem-driver readiness model.', '',
+      '| Format | Optimize | Wipe / clean | Purge | Defrag | Shrink | Compact |',
+      '| --- | :---: | :---: | :---: | :---: | :---: | :---: |',
+    ]
+    for r in sorted(rows,key=lambda r:r['id'].lower()):
+        lines.append(f"| {r['id']} | {mark(r['optimize'])} | {mark(r['wipe'])} | {mark(r['purge'])} | {mark(r['defrag'])} | {mark(r['shrink'])} | {mark(r['compact'])} |")
+    return '\n'.join(lines)
+
+
+def archive_section(rows):
+    visible=[r for r in rows if any(r[k] for k in ('optimize','wipe','purge','defrag','shrink','compact','meta'))]
+    lines=[
+      '## Archive / stream descriptors with at least one operation', '',
+      'Archive **defrag** includes verified repack/relayout (including solid-stream regrouping where the format supports it). '
+      '**Optimize** includes layout tuning and finite compression/dictionary/solid-block parameter search; candidates only win '
+      'after round-trip verification.', '',
+      '| Format | Optimize | Wipe / clean | Purge | Defrag | Shrink | Compact | Meta reorder |',
+      '| --- | :---: | :---: | :---: | :---: | :---: | :---: | :---: |',
+    ]
+    for r in sorted(visible,key=lambda r:r['id'].lower()):
+        lines.append(f"| {r['id']} | {mark(r['optimize'])} | {mark(r['wipe'])} | {mark(r['purge'])} | {mark(r['defrag'])} | {mark(r['shrink'])} | {mark(r['compact'])} | {mark(r['meta'])} |")
+    return '\n'.join(lines)
+
+p=Path('docs/OPERATION_COVERAGE.md')
+t=p.read_text()
+# Canonical verb definitions and defaults.
+t=re.sub(r'\| Purge\s*\| `IArchiveModifiable\.Remove`-all / empty `Create`\s*\|[^\n]*\|',
+         '| Purge           | `IArchivePurgeable`                                  | Erase all live user data, leaving a valid empty container/image; system metadata may be recreated as required by the format. |',t)
+t=t.replace('`Remove(all)` is the **purge** verb.', '`IArchivePurgeable.Purge` is the **purge** verb; `IArchiveModifiable` inherits it because full modification includes removing all live user files.')
+t=t.replace('A filesystem descriptor therefore gains shrink / defrag / purge by simply declaring\nthe interface', 'A filesystem descriptor therefore gains shrink / defrag / purge by declaring\nthe corresponding interface')
+t=t.replace('> **`CanModify` is advertised when the format is a mutable container with a working modify\n> path.** It is withheld only from **read-only-by-design** formats (CramFS, SquashFS) and\n> **create-only** formats — even though a rebuild could synthesise a modified copy, those do\n> not present themselves as editable.',
+'''**`CanModify` means the public API can edit an existing instance and produce a verified valid result.**\nThe physical strategy may be in-place, copy-on-write, relayout/repack, or verified rebuild. Native OS mount\nimmutability (for example CramFS/SquashFS/EROFS) is not the same thing as offline image-editor capability.\nMounted-driver write readiness is tracked separately and remains fail-closed until its durability model is proven.''')
+t=t.replace('- **CramFS**, **SquashFS** — compressed *read-only* filesystems by design; not presented as editable.\n','')
+t=t.replace('- A handful of niche/append-shift formats (MSA per-track RLE; Wrapster/PFS0 header-at-start;\n  OVA manifest-over-all-members; MFS-1 bespoke catalog) keep the rebuild-backed verb without\n  advertising R/W.\n','- Formats whose correct edit necessarily rewrites headers, manifests, tracks, or whole images still advertise R/W when the verified rebuild is their supported existing-instance mutation strategy.\n')
+# Broaden optimize definition to match the runtime implementation.
+t=re.sub(r'\| Optimize\s*\| `ILayoutOptimizable`\s*\|[^\n]*\|',
+         '| Optimize        | `ILayoutOptimizable` / tunable `IFormatOptionsSchema` | Search executable layout/compression parameters and keep the smallest/best verified result. |',t)
+
+fs=scan('FileSystems')
+arc=scan('FileFormats')
+start=t.index('## Filesystem descriptors')
+na=t.index('## N/A notes',start)
+t=t[:start]+fs_section(fs)+'\n\n'+archive_section(arc)+'\n\n'+t[na:]
+
+# Replace stale totals with source-derived advertised counts so the document and interfaces cannot drift in this pass.
+allrows=fs+arc
+counts={k:sum(1 for r in allrows if r[k]) for k in ('defrag','wipe','purge','shrink','optimize','meta')}
+t=re.sub(r'\| Defragment\s*\| \d+ \|',f"| Defragment       | {counts['defrag']} |",t)
+t=re.sub(r'\| Wipe\s*\| \d+ \|',f"| Wipe             | {counts['wipe']} |",t)
+t=re.sub(r'\| Purge\s*\| \d+ \|',f"| Purge            | {counts['purge']} |",t)
+t=re.sub(r'\| Shrink\s*\| \d+\s*\|',f"| Shrink           | {counts['shrink']} |",t)
+t=re.sub(r'\| Optimize \(layout\)\| \d+\s*\|',f"| Optimize         | {counts['optimize']} |",t)
+t=re.sub(r'\| Metadata-reorder\s*\| \d+\s*\|',f"| Metadata-reorder | {counts['meta']} |",t)
+t=t.replace('(Counts are `GetArchiveOps(id) is IXxx` over the registered descriptors — i.e.\nwhat the UI/CLI actually gate on.', '(Counts above are regenerated from explicit descriptor capability interfaces in this tree. Runtime marker/flag consistency is enforced by CI; the UI/CLI gate on the same capability contracts.')
+p.write_text(t)
+Path('.github/coverage-matrix.py').unlink()

.github/merge-readiness.py

@@ -0,0 +1,66 @@
+from pathlib import Path
+
+
+def replace(path, old, new, count=1):
+    p = Path(path)
+    text = p.read_text()
+    if old not in text:
+        raise SystemExit(f'expected text not found in {path}: {old[:120]!r}')
+    p.write_text(text.replace(old, new, count))
+
+# ReFS: wire the already-implemented offline editor into the public descriptor.
+replace('FileSystems/FileSystem.Refs/RefsFormatDescriptor.cs',
+'''  IFormatDescriptor,\n  IArchiveFormatOperations,\n  IFilesystemExtentMap,''',
+'''  IFormatDescriptor,\n  IArchiveFormatOperations,\n  IArchiveModifiable,\n  IFilesystemExtentMap,''')
+replace('FileSystems/FileSystem.Refs/RefsFormatDescriptor.cs',
+'''    FormatCapabilities.CanList | FormatCapabilities.CanExtract | FormatCapabilities.CanTest |\n    FormatCapabilities.SupportsMultipleEntries;''',
+'''    FormatCapabilities.CanList | FormatCapabilities.CanExtract | FormatCapabilities.CanTest |\n    FormatCapabilities.CanModify | FormatCapabilities.SupportsMultipleEntries;''')
+replace('FileSystems/FileSystem.Refs/RefsFormatDescriptor.cs',
+'''  public string Description => "Microsoft ReFS 3.x volume image with native read-only driver projection, namespace/allocation parsing, and offline filesystem-metadata placement support.";''',
+'''  public string Description => "Microsoft ReFS 3.x volume image with native read-only driver projection, namespace/allocation parsing, offline existing-file replacement/removal, and filesystem-metadata placement support.";''')
+anchor = '''\n  private static List<ArchiveEntryInfo> ListDiagnosticSurface(Stream stream) {'''
+insert = '''\n  public void Add(Stream archive, IReadOnlyList<ArchiveInputInfo> inputs)\n    => RefsOfflineModifier.Add(archive, inputs);\n\n  public void Remove(Stream archive, string[] entryNames)\n    => RefsOfflineModifier.Remove(archive, entryNames);\n'''
+replace('FileSystems/FileSystem.Refs/RefsFormatDescriptor.cs', anchor, insert + anchor)
+
+# Maintenance marker tests: purge is its own explicit capability.
+replace('Compression.Tests/Operations/MarkerInterfaceCoverageTests.cs',
+'''    ("purge/modify", typeof(IArchiveModifiable)),''',
+'''    ("purge", typeof(IArchivePurgeable)),\n    ("modify", typeof(IArchiveModifiable)),''')
+
+# Generic purge test must exercise the Purge contract, not approximate it with Remove(all).
+p = Path('Compression.Tests/Operations/GenericPurgeRoundTripTests.cs')
+t = p.read_text()
+t = t.replace('''/// Safety net for the broad rollout of the default <see cref="IArchiveModifiable"/>\n/// (verified extract → edit → re-create rebuild). For every filesystem descriptor\n/// using the DEFAULT Remove, this builds a small image, purges it (Remove every\n/// entry), and asserts the result is a valid, listable, empty container — the\n/// <em>purge</em> verb. The rebuild only commits a result that re-lists, so a writer\n/// limitation surfaces as a clean throw (original untouched) rather than corruption.''',
+'''/// Safety net for the explicit <see cref="IArchivePurgeable"/> capability. For every\n/// purgeable descriptor that can create a representative probe, this builds an image,\n/// invokes Purge, and asserts the user's live files are gone while the result remains\n/// listable. A descriptor that advertises purge must not silently fail or corrupt.''')
+t = t.replace('''  private static IEnumerable<string> ModifiableDefaultIds() =>\n    Compression.Tests.Support.CapabilityImplementers.RegisteredIdsExposing(typeof(IArchiveModifiable))\n      .Where(id => FormatRegistry.GetArchiveOps(id) is IArchiveCreatable\n                   && Enum.TryParse<FormatDetector.Format>(id, out _)\n                   && !Compression.Tests.Support.CapabilityImplementers.DeclaresOwn(id, "Remove", typeof(Stream), typeof(string[])));\n\n  [TestCaseSource(nameof(ModifiableDefaultIds))]''',
+'''  private static IEnumerable<string> PurgeableIds() =>\n    Compression.Tests.Support.CapabilityImplementers.RegisteredIdsExposing(typeof(IArchivePurgeable))\n      .Where(id => FormatRegistry.GetArchiveOps(id) is IArchiveCreatable\n                   && Enum.TryParse<FormatDetector.Format>(id, out _));\n\n  [TestCaseSource(nameof(PurgeableIds))]''')
+t = t.replace('''      var modifiable = (IArchiveModifiable)fmtOps;\n      try {\n        modifiable.Remove(ms, [.. before]);\n      } catch (NotSupportedException) {\n        Assert.Pass($"{formatId}: purge cleanly NotSupported (no corruption).");\n        return;\n      } catch (Exception ex) {\n        Assert.Ignore($"{formatId}: purge rebuild failed non-destructively ({ex.GetType().Name}).");\n        return;\n      }''',
+'''      var purgeable = (IArchivePurgeable)fmtOps;\n      Assert.DoesNotThrow(() => purgeable.Purge(ms),\n        $"{formatId}: advertises IArchivePurgeable but purge failed for its own representative image.");''')
+p.write_text(t)
+
+# Add a root-level purge verb to the CLI. It is deliberately destructive and requires --yes.
+program = Path('Compression.CLI/Program.cs')
+t = program.read_text()
+insert_after = '''replaceCmd.SetAction((ParseResult ctx) => {\n  var archive = ctx.GetValue(replaceArchiveArg)!;\n  var name = ctx.GetValue(replaceNameArg)!;\n  var file = ctx.GetValue(replaceFileArg)!;\n  if (!archive.Exists) { Console.Error.WriteLine($"File not found: {archive.FullName}"); return 1; }\n  if (!file.Exists) { Console.Error.WriteLine($"File not found: {file.FullName}"); return 1; }\n\n  var opts = new CompressionOptions {\n    Method = MethodSpec.Parse(ctx.GetValue(methodOpt)),\n    Level = ctx.GetValue(levelOpt),\n    Password = ctx.GetValue(passwordOpt),\n  };\n\n  Console.Write($"Replacing '{name}' in {archive.Name}...");\n  var sw = Stopwatch.StartNew();\n  ArchiveOperations.Replace(archive.FullName, name, file.FullName, opts);\n  sw.Stop();\n  Console.WriteLine($" done ({sw.ElapsedMilliseconds}ms)");\n  return 0;\n});\n'''
+purge_block = '''\n// ── purge ────────────────────────────────────────────────────────────\n\nvar purgeArchiveArg = new Argument<FileInfo>("archive") { Description = "Archive or filesystem image to empty" };\nvar purgeYesOpt = new Option<bool>("--yes", "-y") { Description = "Confirm destructive purge without prompting" };\nvar purgeCmd = new Command("purge", """\n  Remove all live user entries while leaving a valid empty container/image.\n  This is different from 'wipe': purge removes content; wipe preserves content\n  and sanitizes only unused/dead bytes. The format must advertise IArchivePurgeable.\n\n  Examples:\n    cwb purge disk.d64 --yes\n    cwb purge archive.zip --yes\n  """) { purgeArchiveArg, purgeYesOpt };\npurgeCmd.SetAction((ParseResult ctx) => {\n  var archive = ctx.GetValue(purgeArchiveArg)!;\n  if (!archive.Exists) { Console.Error.WriteLine($"File not found: {archive.FullName}"); return 1; }\n  if (!ctx.GetValue(purgeYesOpt)) {\n    Console.Error.WriteLine("Purge is destructive. Re-run with --yes to remove all live user entries.");\n    return 2;\n  }\n\n  try {\n    FormatRegistration.EnsureInitialized();\n    var formatId = FormatDetector.Detect(archive.FullName).ToString();\n    var ops = FormatRegistry.GetArchiveOps(formatId);\n    if (ops is not IArchivePurgeable purgeable) {\n      Console.Error.WriteLine($"Format {formatId} does not advertise purge support.");\n      return 1;\n    }\n\n    var before = ops.List(File.OpenRead(archive.FullName), null).Count(e => !e.IsDirectory);\n    Console.Write($"Purging {archive.Name} ({formatId}, {before} live file(s))...");\n    var sw = Stopwatch.StartNew();\n    using (var stream = File.Open(archive.FullName, FileMode.Open, FileAccess.ReadWrite, FileShare.None))\n      purgeable.Purge(stream);\n    sw.Stop();\n    using var verify = File.OpenRead(archive.FullName);\n    var after = ops.List(verify, null).Count(e => !e.IsDirectory);\n    Console.WriteLine($" done ({sw.ElapsedMilliseconds}ms; {before} -> {after} live file(s))");\n    return 0;\n  } catch (Exception ex) {\n    Console.Error.WriteLine($"Purge failed: {ex.Message}");\n    return 1;\n  }\n});\n'''
+if insert_after not in t:
+    raise SystemExit('replace command anchor not found in Program.cs')
+t = t.replace(insert_after, insert_after + purge_block, 1)
+t = t.replace('''    cwb wipe-empty disk.img                  Zero all unused space in image''',
+'''    cwb purge disk.img --yes                 Remove all live user entries\n    cwb wipe-empty disk.img                  Zero all unused space in image''', 1)
+t = t.replace('''  listCmd, extractCmd, createCmd, testCmd, addCmd, removeCmd, replaceCmd, infoCmd,''',
+'''  listCmd, extractCmd, createCmd, testCmd, addCmd, removeCmd, replaceCmd, purgeCmd, infoCmd,''', 1)
+program.write_text(t)
+
+# Correct stale operation-model prose without touching generated tables.
+coverage = Path('docs/OPERATION_COVERAGE.md')
+t = coverage.read_text()
+t = t.replace('''No archive descriptor currently implements a dedicated `IArchivePurgeable` interface; purge is represented by `IArchiveModifiable.Remove` over all live entries.''',
+'''Purge is an explicit `IArchivePurgeable` capability. `IArchiveModifiable` inherits it because removing all live user entries is a required subset of full modification; generic purge is staged and verified before commit.''')
+t = t.replace('''CramFS and SquashFS remain read-only/WORM because their on-disk formats are immutable by design.''',
+'''CramFS, SquashFS and EROFS remain read-only when mounted by their native operating-system drivers, but CompressionWorkbench exposes verified offline rebuild-backed modification for supported profiles. Mounted-driver R/W is a separate capability and remains fail-closed where the native format is immutable or crash-consistent mutation is not implemented.''')
+coverage.write_text(t)
+
+# Remove the one-shot machinery in the commit it creates.
+Path('.github/merge-readiness.py').unlink()
+Path('.github/workflows/merge-readiness-once.yml').unlink()