Swift-Liquid 1.2.0

Swift-Liquid 1.2.0

Swift-Liquid 1.2 adds opt-in render metrics to the dependency-free Shopify Liquid
engine. Measure source or reusable parsed templates, retain explicit recovered
diagnostics when needed, and write CLI metrics separately from rendered output.
Existing 1.0 and 1.1 call sites keep their APIs and default behavior.

Requires Swift tools/compiler 6.4 or later, in Swift language mode 6.

Observe one invocation

import Liquid

let engine = LiquidEngine()
let result = try await engine.renderWithMetrics(
    template: "Hello, {{ name }}!", context: ["name": "Swift"]
)
print(result.output)                    // Hello, Swift!
print(result.metrics.outputBytes)       // 13
print(result.metrics.totalDuration)

let parsed = try LiquidTemplate("{{ name }}")
let reused = try await engine.renderWithMetrics(parsed, context: ["name": "Swift"])
assert(reused.metrics.parseDuration == nil)

LiquidMeasuredRenderResult and LiquidRenderMetrics are immutable, checked
Sendable values. Total duration uses a monotonic clock and includes suspended
host callbacks. Source calls also report parsing time for the root and all
supplied partials; parsed calls exclude parsing already done by their caller.
The Liquid date reference clock remains independent.

Counts report supplied-source bytes, final output bytes and consumed evaluator,
loop and context/filter admission capacities. Nested partials share one budget.
These are logical observations of this implementation, not heap/RSS usage,
allocation counts, CPU instructions or a portable cost model. Existing render
APIs collect no timing; their cost is checked through matched measurements.

Use renderWithDiagnosticsAndMetrics for the existing explicit recovery policy.
Recovered output retains diagnostics and is not an error-free render. Syntax,
invalid values, quotas, cancellation and unexpected host errors still throw with
their existing identity. Failed invocations return no partial metrics.

Keep CLI output and metrics separate

liquid render page.liquid --data context.json --output page.html --metrics metrics.json

--metrics PATH writes a separate UTF-8 JSON document with schema version 1,
integer nanosecond durations and logical counts. The CLI measures its prepared
parsed-template call, excluding CLI file I/O and parsing; parse time is null.
Rendered stdout and --output retain their behavior. The inspection JSON schema
is unchanged.

The CLI rejects input/output aliases, including hard links and symlinked parents.
Metrics are written atomically after successful output delivery. Render failure
preserves any prior metrics file. A late metrics write failure exits nonzero even
if output was delivered; the two destinations are not one transaction.

Compatibility and qualification

• Keep one Liquid library, one liquid executable and an empty root dependency
  graph. Engines and templates retain no mutable measurement state.
• Preserve all 99 published 1.1 public symbol declarations, the original 1.0
  consumer, typed filters, inspection, parser modes, limits and error policies.
• Preserve fixture bytes, checksums, licenses and reference pins. The pinned Ruby
  reference evaluates 2,032 core checks: 1,502 successful renders, 337 parsed
  grammar cases, 132 expected errors, 26 recovered errors and 35 supported-year
  boundaries. Host callbacks have 15 separate paired cases. Metrics tests do not
  inflate core conformance accounting.
• Qualify 54 test functions in debug and release, four independent public
  consumers, 60 CLI cases, AddressSanitizer, four ThreadSanitizer concurrency
  cases, compiled DocC and a reproducible clean source-archive rebuild.
• Compile the library against all four declared simulator SDKs. Runtime
  qualification covers macOS; these checks do not certify device execution,
  Linux or WASI. The numeric, UTC and supported-year contracts remain unchanged.

Matched benchmarks compare all 14 common 1.1 workload/mode records with immutable
1.1.0 using its unchanged harness and manifest on one host/toolchain. A separate
candidate comparison measures 24 metrics-enabled/disabled pairs across throwing
and diagnostic policies. Each uses three serial ABBA blocks, six runs per side,
the original sampling policy and verified
output checksums. Measurements and threshold reviews accompany qualification;
this release makes no general speedup or zero-overhead claim.

Upgrade and downloads

Select from: "1.2.0" in SwiftPM and retain the Liquid
product. Existing applications need no migration. Opt into metrics per call;
reuse parsed roots and explicit partial maps as before.

The release includes:

• Swift-Liquid-source.tar.gz: tracked source verified by a clean rebuild.
• Liquid.doccarchive.tar.gz: compiled API reference and guides.
• Swift-Liquid-qualification.tar.gz: gate receipts, logs, source inventory,
  both benchmark comparisons and their reviewed evidence.
• SHA256SUMS: SHA-256 checksums for the three archives.

Verify downloads together with shasum -a 256 -c SHA256SUMS before extraction.
See metrics and schema 1, CLI,
errors and recovery, application reuse and
performance methodology.

Qualification: candidate 8676da8059e71905632c233cffb438f8edbf51d2, source tree 7a3a07ae6bdc5911dc5d539057a3184c07dcc09b, tested as 8676da8059e71905632c233cffb438f8edbf51d2. Exact-source CI evidence.