feat(materialize): declare deterministic file modes

Author: myobie

README.md

@@ -324,9 +324,29 @@ presence is checked only for the selected run host, which defaults to the local
 bare identity or the fully-qualified `<host>.<identity>` bus id.
 
 Materialization simulates all content operations before writing. It refuses any real change to a
-Git-tracked target, including `AGENTS.md`; byte-identical tracked content is accepted. Inspect the
-declared targets and keep generated overlays untracked. Detection invokes `git` and fails closed if
-the executable is unavailable or a workspace that appears to be a worktree cannot be inspected.
+Git-tracked target, including a mode-only change; byte-identical content with the declared mode is
+accepted. Inspect the declared targets and keep generated overlays untracked. Detection invokes
+`git` and fails closed if the executable is unavailable or a workspace that appears to be a worktree
+cannot be inspected.
+
+Each content directive accepts `executable=#true`. st2 applies exact mode `0755` when the property is
+true and exact mode `0644` when it is absent or false. Materialization repairs a wrong existing mode
+even when the file bytes already match. A `copy` source mode does not affect the destination mode.
+An operation whose bytes and mode already match is not reported as materialized.
+
+Inline content uses the existing `file` directive. st2 writes the decoded KDL string without adding
+or removing a newline. A blank line before a multiline string's closing delimiter encodes one final
+newline:
+
+```kdl
+file ".st2/bin/probe" executable=#true {
+  content #"""
+#!/bin/sh
+printf 'ready\n'
+
+"""#
+}
+```
 
 `git-exclude` is advisory. `copy`, `file`, `json-upsert`, and `ensure-line` are boot-gating.
 

docs/vrs/02-agent-spec/spec.md

@@ -264,9 +264,14 @@ st2 `9887b28` predate Resource bindings. Current st2 source:
 <h3 id="f08">F08 <code>render {}</code> operation, template, or resolved target</h3>
 
 Prove ownership for every affected local owner before writing. Conflicts refuse
-all affected owners. Write only changed bytes, then notify survivors that can
-see the committed target. Unchanged bytes do not notify. Deletion needs explicit
-desired state and ownership and never removes a catalog source declaration.
+all affected owners. Write changed bytes and enforce the declared mode. The
+`executable=#true` property selects exact mode `0755`; absence or false selects
+exact mode `0644`. A copy source mode has no effect. Mode-only drift is a
+change. Notify survivors that can see the committed target. Matching bytes and
+mode do not notify and do not report a materialization. Inline `file` content
+uses the decoded KDL string without an added or removed newline. Deletion needs
+explicit desired state and ownership and never removes a catalog source
+declaration.
 
 Authoring: [pinned render contract][evals-render]. st2 implementation and
 evidence: [materializer](../../../src/materialize.rs).

examples/native/README.md

@@ -55,9 +55,15 @@ composer heuristic.
 
 The `render { ... }` block is ordered. `copy`, `file`, `json-upsert`, and `ensure-line` are
 boot-gating operations; a failure prevents that agent from starting. Materialization refuses any
-real change to a Git-tracked target before its first workspace write. A byte-identical tracked
-target is safe and idempotent; untracked and non-Git targets remain writable. `git-exclude` is
-advisory, so a non-Git workspace or exclusion failure does not prevent a boot.
+content or mode change to a Git-tracked target before its first workspace write. A byte-identical
+tracked target with the declared mode is safe and idempotent. Untracked and non-Git targets remain
+writable. `git-exclude` is advisory, so a non-Git workspace or exclusion failure does not prevent a
+boot.
+
+Each content directive accepts `executable=#true`. The property selects exact mode `0755`; its
+absence or false value selects exact mode `0644`. Materialization corrects mode drift even when the
+bytes already match. A `copy` source mode does not affect the destination mode. An unchanged
+operation is not reported as materialized.
 
 Tracked-target detection invokes `git` and fails closed if it cannot inspect a workspace that appears
 to belong to a Git worktree.

src/catalog_transaction.rs

@@ -876,6 +876,7 @@ fn normalize_agent(spec: &agent_spec::AgentSpec) -> Result<BTreeMap<String, Sema
             RenderOp::Copy {
                 source,
                 destination,
+                executable,
             } => {
                 insert_value(
                     &mut fields,
@@ -895,10 +896,17 @@ fn normalize_agent(spec: &agent_spec::AgentSpec) -> Result<BTreeMap<String, Sema
                     SemanticType::String,
                     destination,
                 );
+                insert_default_bool(
+                    &mut fields,
+                    &format!("{root}/executable"),
+                    *executable,
+                    false,
+                );
             }
             RenderOp::File {
                 destination,
                 content,
+                executable,
             } => {
                 insert_value(
                     &mut fields,
@@ -918,11 +926,18 @@ fn normalize_agent(spec: &agent_spec::AgentSpec) -> Result<BTreeMap<String, Sema
                     SemanticType::String,
                     content,
                 );
+                insert_default_bool(
+                    &mut fields,
+                    &format!("{root}/executable"),
+                    *executable,
+                    false,
+                );
             }
             RenderOp::JsonUpsert {
                 destination,
                 content,
                 arrays,
+                executable,
             } => {
                 insert_value(
                     &mut fields,
@@ -954,8 +969,18 @@ fn normalize_agent(spec: &agent_spec::AgentSpec) -> Result<BTreeMap<String, Sema
                         "union",
                     );
                 }
+                insert_default_bool(
+                    &mut fields,
+                    &format!("{root}/executable"),
+                    *executable,
+                    false,
+                );
             }
-            RenderOp::EnsureLine { destination, line } => {
+            RenderOp::EnsureLine {
+                destination,
+                line,
+                executable,
+            } => {
                 insert_value(
                     &mut fields,
                     &format!("{root}/kind"),
@@ -974,6 +999,12 @@ fn normalize_agent(spec: &agent_spec::AgentSpec) -> Result<BTreeMap<String, Sema
                     SemanticType::String,
                     line,
                 );
+                insert_default_bool(
+                    &mut fields,
+                    &format!("{root}/executable"),
+                    *executable,
+                    false,
+                );
             }
             RenderOp::GitExclude { path } => {
                 insert_value(