Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
76 changes: 55 additions & 21 deletions docs/preview2-package-pin.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,43 @@
# Preview-2 Package Pin

Status: internal baseline `2.0.0-preview.6` (2026-08-01) for MCP-6+.
No Release exists for `preview.6`, and none is planned. `2.0.0-preview.2` was
Status: internal baseline `2.0.0-preview.7` (2026-08-01) for MCP-6+.
No Release exists for `preview.7`, and none is planned. `2.0.0-preview.2` was
published as a Release on 2026-07-24 and is superseded — it is history, not a
supported baseline, and preview.3/.4/.5/.6 deliberately did not follow it. SDK-9b
supported baseline, and preview.3/.4/.5/.6/.7 deliberately did not follow it. SDK-9b
closes the Preview-2 gate as an **internal implementation and test acceptance
state only**; public package distribution (GitHub Release assets or nuget.org)
requires explicitly reopening SDK-9a/9b via the staged conditions in the spec.
Decision source: `docs/spec/2026-07-20-plugin-sdk-mcp-decisions.md`,
sections 1, 10, and 12. Preview-1 history: `docs/preview1-package-pin.md`.

## Why preview.7 and not preview.6

`2.0.0-preview.6` was recorded before the automation cross-review fixes, and one of
them added a public contract member: `AuditRecord` gained an optional `Detail`, the
caller-authored annotation an automation `audit.record` action leaves. That is
public surface on `MCServerLauncher.Common` arriving after its fingerprint was
taken, so the baseline moves to `preview.7` rather than being re-cut in place —
same NU1403 rule as every move before it.

Exactly one of the eight packed entries differs from `preview.6`:
`MCServerLauncher.Common`, because its source changed — the new contract member
plus the union-converter strictness that came with the same review. The other
seven — the `Daemon.API` payload and its `buildTransitive` target, the SDK payload,
the packed generator, `NuGet.Versioning`, and the SDK's two `buildTransitive`
assets — are byte-identical to their `preview.6` entries. `Daemon.API` bumped its
`PackageVersion` and did not move, which again shows the bump itself touches no
payload.

The `preview.6` caveat about the SDK facade earned its keep here, and the shape it
predicted is worth recording precisely. Mid-branch, an intermediate state of
`Common` moved the SDK hash to `c52be378…` with no SDK source edit; the final state
moved it back to the value below. So the SDK hash is not a stable function of SDK
source alone, and a reader who packs some intermediate commit of this branch will
see a value that appears nowhere in this document. Only the tree at the recorded
commit is pinned, and `PinnedPayloadHashesMatchTheAcceptanceRecord` is what says so.
Every fingerprint below was reproduced by packing twice into different
`MCSLPinBuildRoot` values, so none of them is build-state noise.

## Why preview.6 and not preview.5

`2.0.0-preview.5` was recorded before the automation trigger and action vocabulary
Expand All @@ -34,7 +62,9 @@ development an intermediate state of `Common` moved the SDK hash without touchin
line of SDK source, and the final state moved it back to the value recorded here.
So an SDK hash that shifts after a `Common`-only edit is not by itself evidence that
something is wrong — `PinnedPayloadHashesMatchTheAcceptanceRecord` is the arbiter,
and it compares a fresh pack against this table on every run.
and it compares a fresh pack against this table on every run. (`preview.7` saw the
same thing again: a `Common`-only change moved the SDK hash mid-branch, and the
state that was finally recorded moved it back.)

## Why preview.5 and not preview.4

Expand All @@ -52,7 +82,7 @@ baseline exists. `MCServerLauncher.Daemon.API` changed because the pinned SDK mo
from `10.0.201` to `10.0.302`; its source is untouched. Both assemblies carry
source-generated JSON metadata, and that generator ships with the SDK, which is why
they moved and `MCServerLauncher.Daemon.Plugin.Sdk`, the packed generator,
`NuGet.Versioning` and the `buildTransitive` assets did not — those five are
`NuGet.Versioning` and the `buildTransitive` assets did not — those six are
byte-identical to their `preview.4` entries.

`PackageVersion` is a NuGet-level version and does not feed the assembly's
Expand All @@ -72,17 +102,17 @@ that mix caches (NU1403), which is the same reason preview.2 was retired.

| Package id | Version |
|---|---|
| `MCServerLauncher.Daemon.Plugin.Sdk` | `2.0.0-preview.6` |
| `MCServerLauncher.Daemon.API` | `2.0.0-preview.6` |
| `MCServerLauncher.Common` | `2.0.0-preview.6` |
| `MCServerLauncher.Daemon.Plugin.Sdk` | `2.0.0-preview.7` |
| `MCServerLauncher.Daemon.API` | `2.0.0-preview.7` |
| `MCServerLauncher.Common` | `2.0.0-preview.7` |

Consumers MUST pin exact versions, without floating ranges, and should use a
lockfile.

### Dependency pins in packages

- `MCServerLauncher.Daemon.API` -> `MCServerLauncher.Common = [2.0.0-preview.6]`
- `MCServerLauncher.Daemon.Plugin.Sdk` -> `MCServerLauncher.Daemon.API = [2.0.0-preview.6]`
- `MCServerLauncher.Daemon.API` -> `MCServerLauncher.Common = [2.0.0-preview.7]`
- `MCServerLauncher.Daemon.Plugin.Sdk` -> `MCServerLauncher.Daemon.API = [2.0.0-preview.7]`
- `MCServerLauncher.Daemon.Plugin.Sdk` embeds both the generator and its
`NuGet.Versioning.dll` analyzer dependency.
- `MCServerLauncher.Daemon.Plugin.Sdk` carries `buildTransitive` props and
Expand All @@ -95,7 +125,7 @@ timestamp metadata that can change across repacks while payload code stays
identical. The fingerprints below cover every DLL that executes in the
consumer build or runtime path, plus every `buildTransitive` asset.

Built from branch `feat/automation-vocabulary` with .NET SDK `10.0.302`; reproducibility
Built from branch `fix/automation-cross-review` with .NET SDK `10.0.302`; reproducibility
requires that exact SDK. `global.json` pins it for both local and CI builds.

`MCSLPinBuildRoot` must be spelled with the platform separator, as the PowerShell
Expand All @@ -119,20 +149,20 @@ one written by a client that ignores it, carries CRLF and hashes differently:
git show HEAD:src/MCServerLauncher.Daemon.Plugin.Sdk/buildTransitive/MCServerLauncher.Daemon.Plugin.Sdk.props | sha256sum
```

### `MCServerLauncher.Common.2.0.0-preview.6.nupkg`
### `MCServerLauncher.Common.2.0.0-preview.7.nupkg`

| Entry | SHA-256 |
|---|---|
| `lib/net10.0/MCServerLauncher.Common.dll` | `14bcfb25c040dbaa6bafd5b87f894101a58858553c67eb2c40f3deab7b5514ee` |
| `lib/net10.0/MCServerLauncher.Common.dll` | `0d124217380de3863791d7e2b06f929bd4bb45a2ba7a837f33b7d07c6b3d3f49` |

### `MCServerLauncher.Daemon.API.2.0.0-preview.6.nupkg`
### `MCServerLauncher.Daemon.API.2.0.0-preview.7.nupkg`

| Entry | SHA-256 |
|---|---|
| `lib/net10.0/MCServerLauncher.Daemon.API.dll` | `e8c687821125a22a4928939b1a5df65932b30a23a6d131f52f532be85c0be922` |
| `buildTransitive/MCServerLauncher.Daemon.API.targets` | `81a79275e7ab2a10cf08ac950c27692db1e7455387944377b06047b0a340c17c` |

### `MCServerLauncher.Daemon.Plugin.Sdk.2.0.0-preview.6.nupkg`
### `MCServerLauncher.Daemon.Plugin.Sdk.2.0.0-preview.7.nupkg`

| Entry | SHA-256 |
|---|---|
Expand All @@ -143,7 +173,9 @@ git show HEAD:src/MCServerLauncher.Daemon.Plugin.Sdk/buildTransitive/MCServerLau
| `buildTransitive/MCServerLauncher.Daemon.Plugin.Sdk.targets` | `e383f4a71ef90a5ad1a25049291c6e877c980d6acac7095ba00778a53f544573` |

The SDK payload DLL fingerprint is unchanged from preview.2 onward: the SDK
assembly itself carries no Preview-2 surface, only the generator does.
assembly itself carries no Preview-2 surface, only the generator does. It is stable
across versions but not across every intermediate state of `Common` within a
version's development, as the note above records.

Build the candidate packages with:

Expand Down Expand Up @@ -213,10 +245,12 @@ ships. The gap is deliberate and bounded; it is recorded here rather than left
implicit so the delivered state is not mistaken for the planned one. The
monitoring metrics row closed in `preview.5`, which is why that baseline exists:
the three items it lists were deferred when `preview.4` was recorded. The two
automation rows closed in `preview.6`, which is why *this* baseline exists —
the disk trigger arrived as a metric on the existing sustained-metric trigger
rather than as a new union member, and the suppression actions brought an
in-memory, instance-scoped hold that resets on daemon restart.
automation rows closed in `preview.6`, which is why that baseline exists — the disk
trigger arrived as a metric on the existing sustained-metric trigger rather than as
a new union member, and the suppression actions brought an in-memory hold, one slot
per instance and scope, that resets on daemon restart. `preview.7` widens no row: it
carries the cross-review correctness fixes to that delivered surface plus the one
audit contract member they needed.

| Area | Delivered | Planned but deferred |
|---|---|---|
Expand All @@ -232,7 +266,7 @@ acceptance criteria rather than folded into this baseline.
## Consumer pin

```xml
<PackageReference Include="MCServerLauncher.Daemon.Plugin.Sdk" Version="2.0.0-preview.6" />
<PackageReference Include="MCServerLauncher.Daemon.Plugin.Sdk" Version="2.0.0-preview.7" />
```

Local-feed restore requires the three nupkgs above and nuget.org for
Expand Down
5 changes: 3 additions & 2 deletions docs/spec/2026-07-20-plugin-sdk-mcp-decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -588,8 +588,9 @@ assets. Where that stands per version:
| `2.0.0-preview.2` | **Published** — Release `2.0.0-preview.2`, 2026-07-24, carries all three nupkgs. Superseded; retained as history, not a supported baseline. |
| `2.0.0-preview.3` | Not published. Frozen Preview-1 baseline, consumed by the MCP repo through a local feed. |
| `2.0.0-preview.4` | Not published. Superseded Preview-2 internal baseline: recorded before monitoring stored disk, responsiveness and lifecycle events, so its `MCServerLauncher.Common` fingerprint stopped describing the tree. |
| `2.0.0-preview.5` | Not published. Superseded Preview-2 internal baseline. Two payloads differ from `.4`, for unrelated reasons: `MCServerLauncher.Common` because its source changed, and `MCServerLauncher.Daemon.API` because the pinned SDK moved from `10.0.201` to `10.0.302` — both carry source-generated JSON metadata and that generator ships with the SDK. The remaining five packed entries are byte-identical. |
| `2.0.0-preview.6` | Not published. Preview-2 internal baseline, same local-feed consumption. One payload differs from `.5`: `MCServerLauncher.Common`, because the automation trigger and action vocabulary was completed in it. The other six packed entries are byte-identical. Fingerprints: `docs/preview2-package-pin.md`, machine-checked by `PinnedPayloadHashesMatchTheAcceptanceRecord`. |
| `2.0.0-preview.5` | Not published. Superseded Preview-2 internal baseline. Two payloads differ from `.4`, for unrelated reasons: `MCServerLauncher.Common` because its source changed, and `MCServerLauncher.Daemon.API` because the pinned SDK moved from `10.0.201` to `10.0.302` — both carry source-generated JSON metadata and that generator ships with the SDK. The remaining six packed entries are byte-identical. |
| `2.0.0-preview.6` | Not published. Superseded Preview-2 internal baseline. One payload differs from `.5`: `MCServerLauncher.Common`, because the automation trigger and action vocabulary was completed in it. The other seven packed entries are byte-identical. |
| `2.0.0-preview.7` | Not published. Preview-2 internal baseline, same local-feed consumption. One of the eight packed entries differs from `.6`: `MCServerLauncher.Common`, because the automation cross-review added an optional `AuditRecord.Detail` and tightened the union converters. The other seven are byte-identical, the SDK facade included — its hash moved mid-branch on an intermediate state of `Common` and moved back, which is the `.6` caveat behaving exactly as recorded. Fingerprints: `docs/preview2-package-pin.md`, machine-checked by `PinnedPayloadHashesMatchTheAcceptanceRecord`. |

So publication is **suspended from `.3` onward**, not retroactively denied. An
earlier revision of this amendment claimed no Release existed for any of the
Expand Down
12 changes: 11 additions & 1 deletion src/MCServerLauncher.Common/Contracts/Audit/AuditContracts.cs
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,15 @@ namespace MCServerLauncher.Common.Contracts.Audit;
/// console content, tokens, and resolved paths are never serialized, which is what keeps the log
/// redaction-safe by construction.
/// </summary>
/// <param name="ErrorCode">
/// A short structured outcome code from the daemon's own closed vocabulary, and null whenever
/// <paramref name="Succeeded" /> is true.
/// </param>
/// <param name="Detail">
/// The one free-text field, and the only one an operator authors: the annotation an automation
/// audit.record action asked to leave. Nothing else populates it, and it is never derived from a
/// request payload. The writer bounds it to 1024 characters, truncating rather than rejecting.
/// </param>
public sealed record AuditRecord(
DateTimeOffset Timestamp,
string Principal,
Expand All @@ -19,7 +28,8 @@ public sealed record AuditRecord(
Guid? OperationId,
bool Succeeded,
string? ErrorCode,
string? ConfirmedBy);
string? ConfirmedBy,
string? Detail = null);

public sealed record AuditQuery(
int? MaximumRecords = null,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -693,20 +693,25 @@ internal static StjJsonException UnknownDiscriminator(string baseTypeName, strin
new($"Unknown {baseTypeName} discriminator '{discriminator}'. Known values: {string.Join(", ", knownValues.Order(StringComparer.Ordinal))}.");

/// <summary>
/// Rejects any property the kind does not define, matching the strictness every source-generated
/// DTO gets from <c>JsonUnmappedMemberHandling.Disallow</c>.
/// Rejects any property the kind does not define or repeats, matching the strictness every
/// source-generated DTO gets from <c>JsonUnmappedMemberHandling.Disallow</c> and
/// <c>AllowDuplicateProperties = false</c>.
/// </summary>
/// <remarks>
/// Ignoring an unknown property is the same failure as coercing a malformed one, and worse for
/// the wildcard-capable kinds: a misspelled 'instance_id' reads as absent, absent means every
/// instance, and a policy meant for one instance would quietly act on the whole fleet.
/// instance, and a policy meant for one instance would quietly act on the whole fleet. A
/// duplicated property is the same harm by a different route — the union reads through a
/// <c>JsonDocument</c>, which keeps every copy and hands back the last, so a second
/// 'instance_id' of null would silently widen the policy the first one scoped.
/// </remarks>
internal static void RejectUnknownProperties(
StjJsonElement obj,
string baseTypeName,
string discriminator,
string[] knownProperties)
{
var seen = new HashSet<string>(StringComparer.Ordinal);
foreach (var property in obj.EnumerateObject())
{
if (!knownProperties.Contains(property.Name, StringComparer.Ordinal))
Expand All @@ -715,6 +720,12 @@ internal static void RejectUnknownProperties(
$"Unknown property '{property.Name}' for {baseTypeName} '{discriminator}'. " +
$"Known properties: {string.Join(", ", knownProperties)}.");
}

if (!seen.Add(property.Name))
{
throw new StjJsonException(
$"Duplicate property '{property.Name}' for {baseTypeName} '{discriminator}'.");
}
}
}

Expand All @@ -739,13 +750,18 @@ internal static int ReadIntOrDefault(StjJsonElement obj, string name, int fallba
return value;
}

// A number JSON accepts but a double cannot hold (1e400) reads back as infinity. Keeping it
// would seat a threshold no reading can reach and then throw on the way back out, because
// infinity has no JSON form to persist the policy with.
internal static double ReadDoubleOrDefault(StjJsonElement obj, string name, double fallback)
{
if (!TryGetScalar(obj, name, out var token))
return fallback;
if (token.ValueKind != StjJsonValueKind.Number)
throw WrongType(name, "number");
return token.GetDouble();
return token.TryGetDouble(out var value) && double.IsFinite(value)
? value
: throw WrongType(name, "finite number");
}

// Derived from the same naming policy the InstanceStatus converter uses, so a status added to
Expand Down
2 changes: 1 addition & 1 deletion src/MCServerLauncher.Common/MCServerLauncher.Common.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
<LangVersion>14</LangVersion>
<IsPackable>true</IsPackable>
<PackageId>MCServerLauncher.Common</PackageId>
<PackageVersion>2.0.0-preview.6</PackageVersion>
<PackageVersion>2.0.0-preview.7</PackageVersion>
<Authors>MCSLTeam</Authors>
<Description>Shared wire contracts and serialization models for MCServerLauncher Future.</Description>
<PackageLicenseExpression>GPL-3.0-only</PackageLicenseExpression>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
<LangVersion>14</LangVersion>
<IsPackable>true</IsPackable>
<PackageId>MCServerLauncher.Daemon.API</PackageId>
<PackageVersion>2.0.0-preview.6</PackageVersion>
<PackageVersion>2.0.0-preview.7</PackageVersion>
<Authors>MCSLTeam</Authors>
<Description>Transport-neutral application and startup-plugin contracts for MCServerLauncher Future.</Description>
<PackageLicenseExpression>GPL-3.0-only</PackageLicenseExpression>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
<LangVersion>14</LangVersion>
<IsPackable>true</IsPackable>
<PackageId>MCServerLauncher.Daemon.Plugin.Sdk</PackageId>
<PackageVersion>2.0.0-preview.6</PackageVersion>
<PackageVersion>2.0.0-preview.7</PackageVersion>
<Authors>MCSLTeam</Authors>
<Description>
Developer SDK for MCServerLauncher Future plugins: feature-gated source generation,
Expand Down
2 changes: 1 addition & 1 deletion src/MCServerLauncher.Daemon.Plugin.Sdk/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Developer SDK for MCServerLauncher Future plugins.
## Install

```xml
<PackageReference Include="MCServerLauncher.Daemon.Plugin.Sdk" Version="2.0.0-preview.6" />
<PackageReference Include="MCServerLauncher.Daemon.Plugin.Sdk" Version="2.0.0-preview.7" />
```

Place `mcsl-plugin.json` beside the project (or under the project directory) and mark a partial class with `[DaemonPluginModule]`.
Expand Down
7 changes: 7 additions & 0 deletions src/MCServerLauncher.Daemon/.Resources/Docs/apifox.json
Original file line number Diff line number Diff line change
Expand Up @@ -2824,6 +2824,13 @@
"string",
"null"
]
},
"detail": {
"type": [
"string",
"null"
],
"default": null
}
},
"required": [
Expand Down
5 changes: 4 additions & 1 deletion src/MCServerLauncher.Daemon/Application/Audit/IAuditSink.cs
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ namespace MCServerLauncher.Daemon.ApplicationCore.Audit;
/// <summary>
/// One observed authorized mutation, described by typed metadata only. Request payloads, command
/// text, console content, and token material are never part of an audit event by construction.
/// <see cref="Detail" /> is the single exception and is caller-authored rather than derived: only
/// an automation audit.record action fills it, with the annotation that action exists to leave.
/// </summary>
internal sealed record AuditEvent(
string Principal,
Expand All @@ -15,7 +17,8 @@ internal sealed record AuditEvent(
Guid? OperationId,
bool Succeeded,
string? ErrorCode,
string? ConfirmedBy);
string? ConfirmedBy,
string? Detail = null);

/// <summary>
/// Fail-open audit recording: implementations must never throw into the mutation path they observe.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,8 @@ public void Record(AuditEvent auditEvent)
auditEvent.OperationId,
auditEvent.Succeeded,
auditEvent.ErrorCode,
auditEvent.ConfirmedBy));
auditEvent.ConfirmedBy,
auditEvent.Detail));
}

internal AuditQueryResult Query(AuditQuery query)
Expand Down
Loading
Loading